The Control-M Application Program Interface (CTMAPI)

This appendix discusses the Control-M Application Program Interface (CTMAPI), including the following topics:

• Overview of CTMAPI

• Environment and Allocations

• CTMAPI Functions

• Conditional Requests and Selection Criteria

• CTMAPI Return Codes

• Conversational Mode Using Program

• Input and Output Registers

• CTMBAPI DSECT

• Status Extension

• Order Extension

• AJF Action Extension

• Global Variable Extension

• Quantitative Resource Extension

• Zoom and Save from CTMAPI

• Create and/or Order or Force a Table (BLT)

• BAPI Replies

• CTMBAPO

Overview of CTMAPI

The Control-M Application Program Interface (CTMAPI) is an open interface between the application environment and Control-M. CTMAPI enables your application program to interface with Control-M so that you can access services and extract data from Control-M into your own programs.

CTMAPI is open to all application environments. It can be called from the following programs or environments:

• High Level Language or Assembler programs, running under various environments, such as CICS, IMS, or the like

• a batch job or step

• REXX or CLIST

However, not all functions of the API are applicable to all environments.

The API can call the CTMAPI module and pass it requests through either of the following:

• a function (command line) passed to CTMAPI, as

  • a parameter from within a program

  • a parameter using PARM=variable in a JCL Batch step

  • an explicit command coded in a dedicated sequential file pointed to by the DAAPI special DDstatement. Note that only bytes 1 through 72 of the records in DAAPI are processed.

  COBOL Examples

  To perform a job order (with FORCE), in the Working-Storage section code:

  Copy

  01  WS-CONTROLM-PARMS.
     05 PARM-LENGTH              PIC 9(4) COMP VALUE 80.
  
     05 PARM-VALUE               PIC X(80) VALUE
  
     'ORDER DDNAME=ddname MEMBER=table-name JOB=job-name FORCE'.

  In the Procedure division code:

  Copy

  CALL 'CTMAPI' USING WS-CONTROLM-PARMS.
  
  IF RETURN-CODE IS GREATER THAN 0 THEN GO TO error-routine.

• conversational mode (CTMBAPI mode), using an area mapped by CTMBAPI DSECT. It passes the request from an application program to CTMAPI, and the results are returned to the calling program

These methods, functions and conversational mode, are explained in more detail in this appendix.

Environment and Allocations

CTMAPI is a callable Load module that resides in the IOA LOAD library. It is located below the line (RMODE=24), works in 31 bit addressing mode (AMODE=31), and can be called by programs running in any AMODE.

The following requirements must be satisfied before CTMAPI can be called:

• The calling application must have access to the IOA LOAD library, either using STEPLIB or using Linklist.

• The standard IOA DDstatement DAPARM must be allocated to the calling address space before calling CTMAPI, and must correctly point to the IOA PARM and IOA IOAENV libraries. This allocation is essential for the correct loading of CTMPARM, IOAPARM and other required parameter members, and to provide the ability to issue messages, dynamically allocate files, and so on.

In addition to the above allocations, each service requires specific data sets to be allocated for successful execution of the service. For example, to successfully order jobs to Control-M, the Active Jobs file (AJF) must be allocated.

CTMAPI relies on IOA dynamic allocation services to allocate the files appropriate to the function, using an ALC member. This means that your program, REXX or batch requires no knowledge of dynamic allocation.

For more information about IOA dynamic allocation and ALC members, see the INCONTROL for z/OS Administrator Guide.

You can tailor CTMAPI to allocate the appropriate files in either of the following ways:

• Let the function itself dynamically allocate the default data sets based on the site standard naming convention (using the default ALC member). Under each function, you can find which ALC member is used to dynamically allocate the necessary files. If you do not require any unusual allocations, this is the recommended method.

• If you want to use other allocations, you can prepare your own ALC member and pass it to CTMAPI using the standard DAALOCIN DDstatement pointing to your own ALC member. If this method is chosen, it is recommended that you use the default ALC member specified in the function as a basis for your own ALC member.

If the caller is not allocated to DAALOCIN DD at the time CTMAPI is called, it is assumed that the default allocations are to be performed. In this case, CTMAPI will dynamically allocate files using the default ALC member.

If CTMAPI is called under the IOA environment, none of the above is applicable. It is assumed that all the necessary files are already correctly allocated, so no dynamic allocation is performed by CTMAPI.

CTMAPI Functions

CTMAPI supports various types of services, but not all of them are supported under all environments. Some of the functions can be executed using existing IOA or Control-M utilities. For example, CTMJOB can be used to order jobs. Other functions, such as the Status request or the Action request, cannot be processed by means of any existing program or utility.

Future enhancements will be provided first to the API rather than to the appropriate utility. BMC therefore recommends that you use CTMAPI for all requests, even functions that are supported using other utilities.

The following CTMAPI functions are available:

• order or force existing jobs into Control-M
  This function can currently also be performed using CTMJOB.

• create and/or order or force a new table into Control-M
  This function can currently also be performed using CTMBLT.

• perform AJF actions equivalent to the following options of the Active Environment screen (Screen 3):

  • Hold

  • Free

  • Delete

  • Undelete

  • Confirm

  • Rerun

  • Restart

  • React

  • Force OK

  • Kill

  • BYPASS commands:

    • BYPJCL (for JCL only)

    • BYPTIME (for Time Limit)

    • BYPCOND (for IN Conditions)

    • BYPQRES (for Quantitative Resources)

    • BYPCRES (for CONTROL Resources)

    • BYPPIPE (for Pipes)

    • BYPWL (for Workload Limits)

    • BYPSCHD (for Scheduling Environment)

    • BYPQTIM (for Quiesce Time)

    • BYPALLC (for All IN Criteria)

    • BYPPOST (for Post Processing)

    • BYPDSUB (for Delayed Submission)

• search and query the status and other details of jobs in Control-M

• resolve, set, and checkpoint variables in the IOA Variables Database

• add, delete, change, or query for conditions or quantitative and control resources.
  This function calls the IOACND utility

• control which jobs in the Active Jobs File are to be excluded from download to Control-M/EM

• check why jobs are in Wait Schedule status

• perform actions on Load-Indexes (obtain a list of Load-Indexes, set the level of an external Load-Index, override the level of a Load-Index, or release an override on a Load-Index)

These functions are described in greater detail in this appendix. Differences in calling the service from different environments are also discussed.

IOAAPI, which is described in the INCONTROL for z/OS Administrator Guide, can be used to perform the following functions:

• CHECK, ADD, or DELETE conditions

• send e-mail messages

• extract records from the IOA Log file

1. Order or Force Existing Jobs

The Order function can be used to order or force an existing table, or selected jobs from an existing table, to Control-M.

This service can be called from any environment, with few differences between environments. The syntax for this service is as follows:

ORDER [REMFORCE] {DSN=schedlib|[DDNAME|DD]=dd} {MEMBER|MEM=table}
[GROUP=group|TBL=group] [JOB=jobnm] [ODATE|DATE=date] [CONTROL-M=REMOTE CONTROL-M] 
[ODATEOPT=VAL|RUN] [FORCE] [INTOTBL=table_rba [DUP|NODUP]] [WTO=N|Y] 
[SETVAR=%%xxx=yyyy] [UFLOW] [SELRBC=rbc]… [IGNRBC=rbc]… [IF if_statement]…

Any number of SETVAR statements can be specified in one ORDER statement. The %% string is mandatory. The equal sign between the SETVAR name and the SETVAR value must be contiguous.

The UFLOW parameter, which specifies that a unique job flow is ordered or forced, is only available when ordering or forcing a table.

For a full description of each parameter, see the description of the CTMJOB utility in the INCONTROL for z/OS Utilities Guide. The only change from the utility is the syntax of the Ignore or Select RBCs and the SETVAR statements. In CTMJOB, the Ignore and Select RBCs are coded separately from the Order statement. Under CTMAPI, they should be coded as part of the Order statement, substituting SELRBC for the keyword SELECT and IGNRBC for the keyword IGNORE. The SETVAR statement can only be specified via CTMAPI. Any job scheduling definition ordered as a result of the Order statement is treated as if it contains the SETVAR statement.

The selection_criteria and if_statement parts of the command are described under Conditional Requests and Selection Criteria.

Specifying WTO=N causes suppression of writing messages to the console.

Order or Force under Batch, REXX or CLIST

When called from a batch job or step or from a REXX or CLIST, the Order statement is specified as one of the following:

• a statement in the format

  Copy

  EXEC CTMAPI PARM=‘ORDER variable’

• in a sequential file pointed to by the DAAPI DDstatement

In this type of call, the SYSPRINT DD statement must be pre-allocated to the step, and the output of CTMAPI written to this file.

A return code is returned in register R15. For a full list of valid return codes, see Order or Force Return Codes.

Force Jobs under a Remote Control-M

REMFORCE schedules jobs under a remote Control-M even if the jobs are not normally scheduled on the specified date (according to the Basic Scheduling parameters of the job). This is similar to the action performed by the DO REMFORCE post–processing parameter.

If REMFORCE specifies a job name that belongs to multiple jobs in the table, the first job in the table with that job name is forced.

REMFORCE must include the CONTROL-M parameter, to specify the remote Control-M server. For a list of valid Control-M server names for use in the CONTROL-M sub-parameter, open the Control-M Configuration Manager (CCM). Valid Control-M server names are displayed in the "Name" column for entries of Type ‘Control-M Server’.

To determine whether a particular datacenter is a mainframe (MF) or a distributed (DS) datacenter, select the entry and in the Properties pane, under the "More properties" section, read what is displayed by the "Operation system" heading. A mainframe datacenter is indicated by "z/OS nn.mm". (Double clicking on the Control-M Server entry will also display the server definitions.)

To successfully execute REMFORCE, the job’s OWNER must be defined in Control-M/EM. When forcing all jobs in a table, the UFLOW subparameter enables you to determine whether the jobs are run as a unique flow.

ORDER REMFORCE MEM=REMFRCEM  CONTROL-M=phx-01.bmc.com  UFLOW
DATE=DATE
SETVAR=%%VAR1=1
SETVAR=%%VAR2=2

Order or Force Using Program

When called from a program, the simplest method of requesting a job order is to pass the Order statement to CTMAPI as a standard parameter. Alternatively, you can use the conversational mode of interface, where the CTMBAPI area is passed as the parameter, and fields in it identify the request. This mode, which is described in Conversational Mode Using Program, is most useful when the calling program requires a reply to be returned to it, for example, to keep track of the Order ID of ordered jobs.

The following statement is an example of the standard method of executing CTMAPI in batch job and passing it an Order request:

//DAAPI  DD *
ORDER DSN=CTM.PROD.SCHEDULE MEM=DEFSCHD1 JOB=JOBA ODATE=ODATE

Order or Force Allocations

For full information, see 1. Order or Force Existing Jobs.

Order or Force Return Codes

Table 274 shows the return codes that can be returned to the caller (in register R15).

Table 274 Order or Force Return Codes

Order or Force Performance Considerations

There are no specific performance considerations with regard to the Order itself. However, using an IF statement can affect the overall performance. For information regarding the impact of an IF statement on performance, see Performance Considerations for Selection Criteria.

Order or Force Security Considerations

The exit called during the Order process is CTMSE01. The files that are accessed, and the type of access, are summarized in Table 275.

Table 275 Files Accessed during the Order or Force Process

2. Create, Order, or Force New Tables

CTMAPI enables the user to create tables, then order or force those tables. You can order or force a table to the Active Jobs File (AJF) even if that table is not in a scheduling library.

This service is similar to that provided by the CTMBLT utility. It is activated by means of appropriate CTMBLT input control statements.

Invoking Create, Order or Force New Tables Using Program

The CTMBLT control statements can be specified in a sequential file pointed to by the DAAPI DD statement, or in an in-core table containing the control statements as 80-byte card images. The first control statement must be the character string 'BLT', beginning in column 1, to indicate that the statements that follow are input for CTMBLT. The rest of the control statements must conform to the usual CTMBLT syntax.

For a full description of the CTMBLT parameters and how to specify whether the tables should be optionally ordered or forced, see the description of the CTMBLT utility in the INCONTROL for z/OS Utilities Guide.

The SYSPRINT DD statement must be pre-allocated to the step. The output of CTMAPI is written to this file. A return code is returned in register R15. A full list of valid return codes is provided in Order or Force Return Codes. When M is specified in the CTMBLT control parameter OPTION, appropriate messages (BLT89AI) are issued to the job log for each table that is created.

Create, Order or Force Allocations

The default ALC member used by the CTMBLT service is ALCMBLT. This allocates the Control-M AJF, IOA LOG, IOA calendars, Control-M Statistics file, and UNITDEF member. These files are required only if the user requests the ordering or forcing of the tables that are built.

Create, Order or Force Return Codes

Table 276 shows the return codes that can be returned to the caller (in register R15).

Table 276 Create and/or Order or Force New Tables Return Codes

Create, Order or Force Performance Considerations

There are no specific performance considerations with regard to CTMBLT itself.

Create, Order or Force Security Considerations

When using the CTMBLT service to create, order, or force a new table, the security considerations are the same as those described in Order or Force Security Considerations.

Table 277 shows the files that are accessed when Order or Force is requested, and the type of access.

Table 277 Files Accessed during the Create, Order or Force Process

3. AJF Actions

Using this type of call to CTMAPI, various actions can be performed against jobs residing in the Active Jobs file (AJF). This service can be called from any environment, with few differences between environments. The full syntax for this service is as follows:

AJF{HOLD|FREE|DELETE|UNDELETE|CONFIRM|RERUN|REACT|FORCEOK|KILL|BYPJCL|BYPTIME|BYPCOND|
BYPQRES|BYPCRES|BYPPIPE|BYPWL|BYPSCHD|BYPQTIM|BYPALLC|BYPPOST|BYPDSUB}
 {selection_criteria}  [selection_criteria]… [SKIPALL]
 [IF if_statement]

The selection_criteria and if_statement parts of the command are described in Conditional Requests and Selection Criteria, and the selection criteria are detailed in Table 282 in Conditional Requests and Selection Criteria.

The SKIPALL option is valid only for the FORCEOK action. It enables you to skip all post-processing actions after the job is forced to be OK. This is equivalent to setting all post-processing options in the Force OK Confirmation Window to N.

§Restart§ Parameters Supported in the RERUN Action

The following parameters are supported in the RERUN action (with Control-M/Restart installed):

Table 277a RERUN Action Parameters Supported by CTMAPI

AJF RERUN MEM=K5 FROMPGM=IOX FROMSTEP=S1 TOPGM=IOX TOSTEP=S3 
RECABEND=Y RECCOND=Y STEPADJ=Y          

AJF Action under Batch, REXX or CLIST

When called from a batch job or step or from a REXX or CLIST, the AJF statement is specified as one of the following:

• a statement in the format

  Copy

  EXEC CTMAPI PARM=‘AJF variable’

• in a sequential file pointed to by a DAAPI DDstatement

In this type of call, only a return code is returned in register R15. A full list of valid return codes is provided in AJF Action Return Codes.

If multiple commands are entered in a DAAPI DD statement, the final return code is the highest return code from any of the commands.

AJF Action Using Program

When called from a program, the simplest method of requesting the appropriate action against a job is to pass the above statement to CTMAPI as a standard parameter. Alternatively, you can use the conversational mode of the interface, where CTMBAPI area is passed as the parameter, and fields in it identify the request. This mode is described in Conversational Mode Using Program.

The following statement is an example of the standard method of executing CTMAPI in batch job and passing it a HOLD request:

//DAAPI  DD *
AJF HOLD MEM=DEFSCHD1 JOB=JOBA OID=0AS45 ODATE=090601 IF STATE=FREE

AJF Action Allocations

The default ALC member used by the AJF Action service is ALCMAJF, which dynamically allocates the AJF only. If you choose to prepare your own ALC member, you must ensure that you allocate at least the above file.

AJF Action Return Codes

Table 278 shows the return codes that can be returned to the caller (in register R15).

Table 278 AJF Action Return Codes

AJF Action Performance Considerations

There are no specific performance considerations with regard to the Action itself. However, the Selection Criteria or IF statement can significantly affect the overall performance. For information regarding the impact of Selection Criteria and/or IF statements on performance, see Performance Considerations for Selection Criteria.

AJF Action Security Considerations

The exit that is called during execution of the action is CTMSE08.

Table 279 shows the files that are accessed, and the type of access.

Table 279 Files Accessed during the AJF Action Process

4. Search

The Search function can be used to

• check the existence of a job in the AJF

• retrieve selected jobs (to a 'reply' area)

• list and count the jobs

which satisfy the selection criteria.

It can be called from any environment. When invoking the SEARCH via CTMBAPI mode the selected AJF entry of the job(s) are returned to the caller. In all other environments, only the selected job list and return code, indicating whether or not the job(s) exist in the AJF, are returned to the caller.

This function should only be used when you want to execute your own process based on the result of this search or you simply want to list the jobs which satisfy the search criteria. If you want to execute one of the other CTMAPI functions based on the Search result, it is recommended that you use the conditional form of that function instead.

The full syntax for the Search call is as follows:

SEARCH selection_criteria [selection_criteria]…

The various valid selection_criteria are described in Conditional Requests and Selection Criteria and Table 282 in Conditional Requests and Selection Criteria.

Search under Batch, REXX or CLIST

When called from a batch job or step or from a REXX or CLIST, the Order statement is specified as one of the following:

• a statement in the format

  Copy

  EXEC CTMAPI PARM=‘SEARCH variable’

• in a sequential file pointed to by DDstatement DAAPI

In this type of call, only a return code is returned in register R15. A full list of valid return codes is provided below.

If multiple commands are entered in DAAPI, the final return code is the highest return code from any of the specified commands.

Invoking Search from a Program

When called from a program, the simplest method of searching for a job is to pass the Search call statement to CTMAPI as a standard parameter. Alternatively, you can use the conversational mode of the interface, where the CTMBAPI area is passed as the parameter, and fields in it identify the requested job. This mode is described in Conversational Mode Using Program. As mentioned earlier, the advantage of using the CTMBAPI mode is that your program gets back from CTMAPI the entry of the job, mapped by CTMBJSE DSECT, as described in The Status Reply DSECT (CTMBJSE).

The following statement is an example of the standard method of executing CTMAPI in batch job and passing it a SEARCH request:

//DAAPI  DD *
SEARCH MEM=DEFSCHD1 JOB=JOBA OID=0AS45 ODATE=090601

Search Allocations

The default ALC member used by the Search service is ALCMAJF, which dynamically allocates the AJF only. If you choose to prepare your own ALC member, you must ensure that you allocate at least the above file.

Search Return Codes

Table 280 shows the return codes that can be returned to the caller (in register R15).

Table 280 Search Action Return Codes

Search Performance Considerations

There are no specific performance considerations with regard to the Search itself. However, the Selection Criteria can significantly affect the overall performance. For information regarding the impact of Selection Criteria on performance, see "Performance Considerations for Selection Criteria" on page 913.

Search Security Considerations

This function does not call any security exit during the Search process.

Table 280 shows the files that are accessed, and the type of access.

Table 280 Files Accessed during the AJF Action Process

5. Global Variables

You can use CTMAPI to set variables in the IOA Variable Database.

• The SET command inserts or updates a global variable in the IOA Variable Database.

• The CKP (CHECKPOINT) command writes all variables which have been SET in the IOA Variable Database to disk.

• The SETCKP command combines the action of both the SET and the CKP commands.

For compatibility reasons, the CKP and SETCKP commands are still valid but the actual check-pointing is done by the monitor on its next interval.

The resolve option is available only when CTMAPI is called in Conversation mode.

The full syntax for this CTMAPI service is

GLOBAL {SET | SETCKP | CHECKPOINT | CKP}
{PRODUCT=x APPL=xxx GROUP=xxx MEMBER=xxx VAR=%%\xxx VALUE=xxx}

If the action to be performed is SET or SETCKP, the name of the variable must be supplied. The keyword parameters are used to define the variable name.

For more information on the actions and components of the variable name, see the IOA administration chapter in the INCONTROL for z/OS Administrator Guide.

Global Variables under Batch REXX or CLIST

If you are calling this function from a batch job, REXX, or CLIST, the GLOBAL statement can be specified in one of the following:

• a statement with the following syntax

  EXEC CTMAPI PARM='GLOBAL action | varname'

  where:

• action has one of the following values:

  • SET

  • SETCKP

  • CHECKPOINT

  • CKP

• varname is the name of a global variable

• a sequential file pointed to by the DAAPI DDstatement

If you use a DAAPI file, you can insert multiple commands.

6. Conditions and Resources

You can use CTMAPI to

• add, delete, or query conditions

• add or delete control resources

• add, delete, or change quantitative resource

For these actions, CTMAPI actually calls the IOACND utility. The syntax is the same as the syntax for the IOACND utility, prefixed with the command word COND or RES.

COND {ADD | DELETE | CHECK} COND cond-name ODATE
RES {ADD | DELETE} CONTROL control-name {EXCLUSIVE | SHARE} [DUPRES=Y|N]
RES ADD RESOURCE res-name quantity
RES DELETE RESOURCE res-name
RES CHANGE RESOURCE res-name [-|+]quantity

RES ADD CONTROL RES123 EXCLUSIVE DUPRES=N

For more information on the syntax of the IOACND utility and its characteristics, see the IOACND section in the INCONTROL for z/OS Utilities Guide.

In addition, you can use CTMAPI in batch mode to query quantitative and control resources. For such actions, use the Resource check command:

RES CHECK RESOURCE Res_Name Res_type

Where:

• Res_Name is the name of the quantitative/control resource

• Res_type is the type of resource, one of the following:

  • Q: Quantitative

  • C: Control

  • A: All

7. CTMAS Active Job Download Filtering

You can use the CTMAPI EMDOWNLD service to control which job in the Active Job File will be downloaded to Control-M/EM during download processing of the Control-M Application Server (CTMAS).

• The EXCLUDE command excludes the job(s) specified from being downloaded to Control-M/EM

• The ACCEPT command indicates to CTMAPI to no longer exclude the job(s) specified from being downloaded to Control-M/EM

The full syntax for this service is as follows:

EMDOWNLD{EXCLUDE|ACCEPT}
{selection_criteria} [selection_criteria]…
[IF if_statement]

The selection_criteria and if_statement parts of the command are described in Conditional Requests and Selection Criteria. The selection criteria are detailed in Table 282 in Conditional Requests and Selection Criteria.

The EMDOWNLD service also includes the following specific syntax commands:

• EXCLUDE LIST – List all jobs currently excluded from download to Control-M/EM

• ACCEPT ALL – Include all currently excluded jobs in the next download to Control-M/EM

EMDOWNLD Action under Batch, REXX or CLIST

The EMDOWNLD service can be called from a batch job or step or from a REXX or CLIST, in one of the following ways:

• a statement in the format

  Copy

  EXEC CTMAPI PARM=‘EMDOWNLD variable’

• in a sequential file pointed to by DDstatement DAAPI

In this type of call, only a return code is returned in register R15. A full list of valid return codes is provided in AJF Action Return Codes.

If multiple commands are entered in DAAPI, the final return code is the highest return code from any of the specified commands.

EMDOWNLD Action Allocations

For information on EMDOWNLD action allocations, see AJF Action Allocations.

EMDOWNLD Action Return Codes

For information on EMDOWNLD action return codes, see AJF Action Return Codes.

EMDOWNLD Action Performance Considerations

For information on EMDOWNLD action performance considerations, see AJF Action Performance Considerations.

EMDOWNLD Action Security Considerations

For information on EMDOWNLD action performance considerations, see AJF Action Performance Considerations.

Examples for EMDOWNLD

//S1 EXEC PGM=CTMAPI,PARM='EMDOWNLD EXCLUDE OID=000DB’

//S1 EXEC PGM=CTMAPI,PARM='EMDOWNLD ACCEPT MEMBER=BR14’

//S1 EXEC PGM=CTMAPI,PARM='EMDOWNLD EXCLUDE LIST’

8. Batch Mode WHYWAIT

The CTMAPI WHYWAIT service enables you to check why a job is in Wait Schedule status. This information is similar to the information provided in the Why screen (Screen 3.?).

For the WHYWAIT service, use the following syntax:

WHYWAIT MEMBER=memname ORDERID=orderid   GROUP=group_name
        OWNER=owner    ODATE={ODAT|date}

9. Batch Mode WAIT

The CTMAPI WAIT service enables you to specify a time interval between the execution of two CTMAPI commands for jobs in batch mode.

Define the time interval using a WAIT value with 5 characters:

• The first four characters are numeric, to define a number with 4 digits.

• The last character determines the unit: S (seconds) or M (minutes)

AJF,HOLD,MEM=A12TJ2,OID=0007M
WAIT=0006S
AJF,DELETE,MEM=A12TJ2,OID=0007M

10. Load-Index Optimization Actions

LOAD-INDEX (or LIND) modify commands enable you to query and modify the defined Load-Indexes.

For more information about Load-Indexes, see Using Load-Indexes in Workload Optimization.

You can perform the following actions:

Table 273a Load-Index Modify Commands

List Details of Load-Indexes

The LOAD-INDEX LIST command (or LIND LIST command) obtains a list of defined Load-Indexes.

Use the following API command:

LOAD-INDEX LIST NAME=,parameters

The following parameters can be used in this command to limit the scope of Load-Indexes included in the list:

Table 273b Parameters of the LOAD-INDEX LIST Command

CTML0GI NAME=LINDEX1          TYPE=4HRA DESC=FIRST LOAD-INDEX    
CTML0MI LEVEL=MEDIUM OVERRIDDEN=Y SET AT=2019/10/02 11:47:00 BY=M37 NOTE=
IOA728I -------------------------------------------------------------------
CTML0GI NAME=LINDEX2          TYPE=EXT  DESC=EXTERNAL LOAD-INDEX
CTML0MI LEVEL=HIGH   OVERRIDDEN=N SET AT=2019/10/02 09:47:33 BY M37 NOTE=
IOA728I -------------------------------------------------------------------
CTML0GI NAME=LINDEX3          TYPE= UTIL DESC=    
CTML0MI LEVEL=IDLE   OVERRIDDEN=N SET AT=2019/10/02 09:47:13 BY M37 NOTE=
IOA728I -------------------------------------------------------------------
IOA72TI SEARCH COMPLETE. NUMBER OF ENTRIES FOUND:       3

Set the Level for an External Load-Index

The LOAD-INDEX SET command (or LIND SET command) sets a load level value for an external Load-Index (type EXT).

Use the following API command:

LOAD-INDEX SET,parameters

The following parameters can be used in this command:

Table 273c Parameters of the LOAD-INDEX SET Command

LOAD-INDEX SET NAME=* NEWLEVEL=HIGH

WLI031I LOAD-INDEX LINDEX2              WAS SET TO LEVEL HIGH
WLI035W LOAD-INDEX LINDEX3               NOT EXTERNAL, SKIPPED
WLI03BI ACTION PERFORMED WITH WARNING,    1 LOAD-INDEXES MODIFIED

Override the Level of a Load-Index

The LOAD-INDEX OVERRIDE command (or LIND OVERRIDE command) overrides the load level of a Load-Index with a new value.

Use the following API command:

LOAD-INDEX OVERRIDE, parameters

The following parameters can be used in this command:

Table 273d Parameters of the LOAD-INDEX OVERRIDE Command

LOAD-INDEX OVERRIDE NAME=* NEWLEVEL=HIGH

WLI032I LOAD-INDEX LINDEX3              WAS OVERRIDDEN TO HIGH
WLI03BI ACTION PERFORMED SUCCESSFULLY,    1 LOAD-INDEXES MODIFIED

Release a Load-Index Override

The LOAD-INDEX RELEASE command (or LIND RELEASE command) releases an override on a Load-Index, restoring its load level to the most recently measured or most recently set value.

Use the following API command:

LOAD-INDEX RELEASE, parameters

The following parameters can be used in this command:

Table 273e Parameters of the LOAD-INDEX RELEASE Command

LOAD-INDEX RELEASE NAME=*

WLI033I LOAD-INDEX LINDEX3              WAS RELEASED TO LOW
WLI03BI ACTION PERFORMED SUCCESSFULLY,    1 LOAD-INDEXES MODIFIED

Conditional Requests and Selection Criteria

Many services can be conditionally executed based on various terms and conditions. This topic describes in more detail the various criteria that can be used.

Poor usage of selection criteria can dramatically impact the overall performance. Before using such selection criteria, read Performance Considerations for Selection Criteria.

The full syntax for the selection criteria is as follows:

[IF] {[MEM=memname*] | [GROUP|GRP=group_name*] | [TABLE|TBL=table_name*] |
[JOB=job_name*] | [JOBID=jes_job_number] |
[OWNER=owner*] | [OID=orderid] | [ODATE={ODAT|date}] |
[RECTYPE={JOB|TAB|ALL}] |
[STATUS={WAIT_SCH | WAIT_TIME | WAIT_CONF | WAIT_PIPE | WAIT_ORD | EXEC_ERR | EXEC_WSUB |
EXEC_INQ | EXEC_NJE | END_OK | END_OK_FOK | END_NOK_ABND | END_NOK_JCLE | END_NOK_UNKW | 
END_NOK_CC | END_NOK_NSUB | END_NOK_DISA | ENDED | NOT_ENDED | EXIST | NOTEXIST |
NOT_DELETED | DEL} ] |
[STATE={HOLD|FREE}]}
[{AND|OR} selection2 }]...

Parameters marked with an * (asterisk) to the right of the field value are used as a prefix for the specified selection criteria. No masking is allowed in any other field.

For example, MEM=ABC* means select jobs whose MEMNAME prefix is "ABC". Coding MEM=* is the equivalent of omitting the MEM selection criteria, that is, all MEMNAMEs are eligible for selection.

Note that the same parameters can be used as Selection Criteria or IF statement Criteria, but their functionality differs.

• Selection Criteria: Used to select all jobs on the AJF to be acted upon.

• IF Criteria: Used to determine if any action will be taken. If any job on the AJF matches the IF criteria, the action is taken.

Table 282 Selection and IF statement Criteria Parameters

The processing logic of the statement

ctmapi-command action {list of selection-criteria} IF {list of if-criteria}

is as follows:

• CTMAPI first finds all jobs on the AJF which match the Selection Criteria. It then determines if any job on the AJF matches the IF Criteria. If even one job on the AJF matches the IF criteria, then EVERY job which matched the Selection Criteria is acted upon by the command action; otherwise the action is not performed (Reason 220 in message IOA723I) and the utility ends with a return code of 4.

• If there is no IF clause then CTMAPI simply acts on all the jobs satisfying the selection-criteria unconditionally.

AJF CONFIRM MEM=YOURJOB* IF MEM=MYJOB STATUS=END_OK

AJF DELETE GRP=MYGRP OWNER=MYUSER IF (STATUS=WAIT_SCH OR STATE=HOLD) AND MEM=MYJOB

Performance Considerations for Selection Criteria

The overall performance of each call to CTMAPI is largely dependent on the selection criteria. These must be carefully considered.

An important factor affecting overall performance is the uniqueness of the selection criteria. If very few jobs in the Active Jobs file conform to your selection criteria, then very few job records will have to be handled. For example, if you search for a specific Order ID, the result will be the reading of only a few index records and only one job record. On the other hand, if you search for all jobs with a member name starting with ABC, the API must read many job records as well as the index records.

You can greatly improve overall performance by using indexed fields in the selection criteria. This results in a faster and more efficient search. The use of non-indexed fields causes a sequential search through the Active Jobs file, which is very slow and inefficient.

Table 283 shows the attributes of each selection criteria parameter.

Table 283 Selection Criteria Parameter Attributes

As Table 283 shows, OID is the best choice for selection criteria, since it is both indexed and unique. On the other hand, ODATE and JOBID are the worst choices for selection criteria, since they are neither indexed nor unique. If you must use one of the non-indexed search criteria, BMC recommends using it in a combination with other indexed criteria.

Another factor affecting overall performance is the complexity of any AND or OR statements that qualify the selection criteria. Statements included in an AND or OR section of the selection criteria are each handled separately, one by one, as if each is a fully qualified selection criteria, and the whole Boolean sentence is verified only after each such statement is checked.

Search Security Considerations (Conditional Requests)

This function does not call any security exit during the Search process.

Table 284 shows the files that are accessed, and the type of access.

Table 284 Files Accessed during the AJF Action Process

CTMAPI Return Codes

CTMAPI return codes are returned in register R15. They are also returned in the following fields:

• BAPIRC

• BAPIRSN

• BAPIURC

The following are the types of failure of CTMAPI:

• CTMAPI itself encountered a problem that prevented it from calling a service.

  In this case

  • register R15 has a value higher than 8

  • the reason code is returned in the BAPIRSN field

• The service was activated, but failed to perform the desired action.

  In this case

  • register R15 has a value of 8

  • the return code from the service is returned in the BAPIURC field

Conversational Mode Using Program

This type of call is intended for use by programs. It enables the program to pass requests, accept replies, respond on the basis of the reply, and maintain communication between the program and the API.

The basic communication area, which is passed back and forth between the calling program and the API, is mapped by the Assembler DSECT CTMBAPI, which can be found in the IOA MAC library. Different fields in this DSECT identify the request, specify the selection criteria, and pass the address of the area in which replies to the caller are to be returned.

Input and Output Registers

On input to any CTMAPI service, the contents of the general-purpose registers should be as shown in Table 285.

Table 285 Contents of Registers on Input to CTMAPI

On return, all registers are restored by CTMAPI, and a return code is returned in register R15. In this appendix, the return codes and their meanings are explained under each service.

Examples: Invoking CTMAPI in BAPI Mode

         LOAD  EP=CTMAPI
         LR    R15,R0
         OI    BAPIADR,X'80'
         LA    R1,BAPIADR    POINT TO BAPI AREA ADDRESS
         BALR  R14,R15       CALL CTMAPI
         .... 
BAPIADR  DC    A(BAPIDSLN)   BAPI DSECT + HALFW LEN   
         DS    0D            DOUBLEWORD ALIGNMENT
         DS    CL6           6 BYTE FILLER
BAPIDSLN DC    Y(BAPILEN)    HALFWORD LENGTH FROM CTMBAPI DSECT
CTMBAPI  DSECT=NO

         OI BAPIADR,X'80'
         LA R1,BAPIADR                POINT TO BAPI AREA ADDRESS
         ATTACH  EP=CTMAPI,ECB=ECB    ATTACH CTMAPI as a subtask
         WAIT   ECB=ECB               Wait for the subtask to end
  
....
....
ECB      DC    A(0)
BAPIADR  DC    A(BAPIDSLN)   BAPI DSECT + HALFW LEN
         DS    0D            DOUBLEWORD ALIGNMENT
         DS    CL6           6 BYTE FILLER
BAPIDSLN DC    Y(BAPILEN)    HALFWORD LENGTH FROM CTMBAPI DSECT
         CTMBAPI DSECT=NO

CTMBAPI DSECT

This section describes in more detail

• how to use the CTMBAPI DSECT

• what fields the caller should set

• what fields are used to return the result

The explanation assumes the use of Assembler language. However, you can use other high level languages to implement most of the services, provided the language you use conforms to the standard calling conventions in Table 285.

The type of service is identified in one or both of the following ways

• as a command within a buffer
  The start address of the buffer is passed to the API using the BAPICMDA field. The command length is passed using the BAPICMDL field.

• using the BAPICMD field, which identifies the type of service

If both are specified, the command takes precedence.

CTMBAPI is composed of

• a fixed part
  This is used to identify the requested service, together with other necessary fields.

• a variable (extension) part
  This is in variable format, where each service uses a different extension.

For each service, the format of each extension is documented in the following sections of this appendix, for example in Status Extension, Order Extension, AJF Action Extension, and so on.

The fields in the fixed (header) part are summarized in Table 286. The values in the columns in Table 286 have the following significance:

• In the column headed "Optional or Mandatory"

  • M means mandatory

  • O means Optional

• In the column headed "In or Out"

  • I means Input

  • O means Output

• In the column headed "Type"

  • CLnn means a character field nn characters in length, padded with blanks to the right.
    If omitted, it must be set to blanks.

  • an *(Asterisk) to the right of the CLnn entry means that the characters in the field are used as a prefix for the specified selection criteria.
    For example, if you specify MEMNAME ABC*, all jobs with a MEMNAME prefix of "ABC" will be selected.

  • A means Address, a 4-byte fullword field pointing to an area.
    If omitted, it must be set to binary zero.

  • F means Fullword, a 4-byte fullword field containing a binary number.
    If omitted, it must be set to binary zero.

  • H means Halfword, a 2-byte halfword field containing a binary number.
    If omitted, it must be set to binary zero.

  • Flag means a Flag Byte, where each bit has a separate significance.

Table 286 Fixed Part Values

Status Extension

The value of 2 (BAPI_M_STATUS) should be set in the BAPICMD field for the Status function.

The Status function can be used to retrieve information about jobs in the Active Jobs file. This service can be called from any environment, but only by using the CTMBAPI mode, that is, using a program, and not by means of a batch statement, REXX or CLIST.

On return, the status of and other information about the job is returned to the caller.

If you only requested one job, for example, Status using OID, the result is returned in the Status extension itself. If more than one job may conform to the selection criteria, for example, the status of MEMNAME ABC, a reply buffer must be supplied into which the API can return a result for each and every job that conforms. If no such buffer is supplied, no reply other than an appropriate return code is returned.

The Status extension fields are summarized in Table 287. If the caller filled in a field, it is used as Search argument, and only jobs that conform to that field are returned. On return from the API, if no reply area has been supplied, and if only one job conforms to the selection criteria, the API will fill in all these fields with actual information about this job. For example, if you specify ABC in BAPISMEM, and there is only one job in the AJF with a matching MEMNAME, such as ABCXYZ, on return from the API this field will hold the value ABCXYZ.

The values in the columns in Table 287 have the same significance as those in Table 286.

Table 287 Status Extension Fields

The Status Reply DSECT (CTMBJSE)

The DSECT that formats reply area entries is CTMBJSE. Each entry is 240 bytes long. For REXX parsing, fields in this DSECT are separated by a blank.

You must always allocate an area of 12,000 bytes and code its address in the BAPIRPLS field.

The search criteria can fit multiple jobs on the AJF, up to a maximum of 50 jobs. For example, if you want to process 25 jobs, prepare an area of 12,000 bytes and code its address in the BAPIRPLS field. After returning from the API, the area will contain the details of the 25 jobs. Each job line is detailed in the CTMBJSE DSECT and contains relevant information about the located job.

The number of lines is returned in the BAPIRPL# field. When this field points to the maximum, 50, it is possible that there are more lines that can be returned. In that case, the value of the Utility Return Code field BAPIURC will be 4, and the Reason Code field BAPIRSN will have the value "BAPI_HAVE_MORE_LINES." In such a case, the user program can set bit BAPISPF8 in byte BAPISF1 and call CTMAPI again. This call will retrieve the next 50 lines of output that match the search criteria. When multiple lines are returned, the lines are in the order from the end (the most recent job) to the beginning. There is an option for the calling program to receive only one line of output, by specifying as the value in the BAPISF1 flag byte either BAPIS1ST (first line) or BAPISLST (last line).

Except for field JSESTAT, the meanings of the fields are as described (internally) in the macro CTMBJSE, which is in the IOA MAC library. The JSESTAT field returns the status of the job in the AJF. The CTMAPI status function does not return all the statuses detailed in the Control-M for z/OS User Guide. A list of the statuses that can be returned appears in Table 288.

Table 288 Statuses Returnable under the Status Function

Status Allocations

The ALC member used by the Status service as the default is ALCMAJF, which dynamically allocates the AJF only. If you choose to prepare your own ALC member, you must ensure that you allocate at least the above file.

Status Return Codes

Table 289 shows the return codes that can be returned to the caller (in register R15).

Table 289 Status Return Codes

Status Performance Considerations

The Status function searches the AJF for the requested jobs. More than one job may conform to the selection criteria specified in the CTMBAPI DSECT. In that case, a Job Status Element (JSE) entry is returned to the caller for each job.

The Selection Criteria can significantly affect overall performance.

• The more specific the request, the fewer the jobs that must be read and returned to the caller. For example, if you request status information for all jobs starting with the letter A, the function must read a large part of the AJF, degrading its performance.

• Pay special attention to whether your search criteria are indexed. If you ask for status information about jobs with a selection criteria that is not indexed, for example, from a specific ODATE, without any indexed selection criteria, the whole AJF must probably be read.

The impact of Selection Criteria on overall performance is described in Performance Considerations for Selection Criteria.

Status Security Considerations

This function does not call any security exit during the Status process.

The files that are accessed, and the type of access are summarized in the following table:

Table 290 Files Accessed during the AJF Action Process

Order Extension

The value that should be set in the BAPICMD field for this function is 1 (BAPI_M_ORDER).

You can use the Order function to order jobs to the AJF. You can call this function from any environment, but only by using the CTMBAPI mode. The function uses the usual Control-M order process to put the requested job on the AJF. The return code will appear in the BAPIURC (Utility Return Code) field.

If CTMAPI fails to invoke the order process, register R15 will contain a value of 8 or higher, and the reason code will appear in the BAPIRSN field.

You can request a detailed reply from the order process, using the following procedure:

Begin

1. Prepare a memory area.

2. Pass the start address in the BAPIRPLS field.

3. Pass the address of the last byte of this area in the BAPIRPLE field.

   After returning from the order process, the BAPIRPLC field will point to the last byte replied. The BAPIRPL# field will contain the number of reply lines. For each job processed by the order process, a reply line will be returned detailing the job identifiers and the RC of the order for this specific job. This is in contrast to the usual output lines of the order process that are issued only for jobs that have actually been ordered. Details of the reply line are specified in the CTMBAPO DSECT.

   Table 291 contains a summary of the CTMBAPI Order input fields. You must ensure that all fields whose type is CL are initialized with BLANKS, and those with type X are initialized to binary zeros.

   Table 291 Order Fields

   Field Name	Optional	In or Out	Type	Usage
   BAPIODSN	N	I	CL44	Table DS name. Mutually exclusive with BAPIODD.
   BAPIOMEM	N	I	CL8	Member name
   BAPIODD	O	I	CL8	Table DD name. Mutually exclusive with BAPIODSN.
   BAPIOJOB	O	I	CL8	Job name. Enter ‘  ‘ (Blank) to order all jobs in the table.
   BAPIODAT	O	I	CL6	ODATE. Default is the current Odate.
   BAPIORBA	O	I	CL6	RBA of the SMART Table Entity when a Dynamic SMART Table Insert is performed.
   BAPIOF1	O	I	XL1	Flags byte. Valid values are: X’80’ – Force the table X’40’ – Insert the job into a SMART Table Entity that already exists on the AJF X’20’ – Allow duplicate jobs in the group when dynamically inserting a job into the group From X’10’ through X’01’ – These bits are reserved for internal use
   BAPIRBC#	O	I	XL2	Number of rule-based calendar statements that follow this field. This field is for users who want to implement the IGNORE and/or SELECT RBC logic that is discussed on connection with the utility CTMJOB in the Control-M chapter of the INCONTROL for z/OS Utilities Guide. After this field, you should code the matching number of BAPITGNM statements that define the rule-based calendars themselves.
   BAPITGIN	O	I	CL1	Ignore or Select indicator. Valid values are: I – Ignore S – Select
   BAPITGNM	O	I	CL20	RBC name

Order Return Codes

Table 292 shows the return codes that can be returned to the caller (in register R15).

Table 292 Order Return Codes

Order Reply

The conversational mode (BAPI) order process can return a reply line for each job processed. The reply line is mapped by DSECT CTMBAPO, which is described in more detail in CTMBAPO.

Order or Force Allocations

For full information, see 1. Order or Force Existing Jobs.

Order or Force Security Consideration

For full information, see 1. Order or Force Existing Jobs.

AJF Action Extension

The AJF Action function can be used to perform basic Active Environment screen (Screen 3) actions upon jobs in the AJF. Using the BAPI interface, a user program is able to perform actions such as holding, freeing, deleting jobs in the AJF in much the same manner as the user can from Screen 3.

For this function, set the value in the BAPICMD field to 3 (BAPI_M_ACT).

The Action function can be called from any environment. The input contains the following types of input:

• to identify the job

• to define the Action upon the job

These are described in the following sections.

Identifying the Job

The first type of input identifies the job, using the field names in Table 293.

Table 293 AJF Action Parameters

CTMAPI uses this variable to find the job in the same way it does a search. For information concerning performance and security, see Create, Order or Force Performance Considerations.

Defining the Action

To define the Action, you must set a 1-byte field called BAPIAACT with one of the values in Table 294

Table 294 AJF Action BAPIAACT Field Values

Action Return Codes

The CTMAPI Action return code is returned in register R15. There are basically two types of failure:

• The CTMAPI program itself encountered a problem which prevented it from calling the service. In this case

  • register R15 has a value higher than 8

  • the reason code is returned in the BAPIRSN field

• The service was activated but failed to perform the desired action. In this case

  • register R15 has a value of 8

  • the return code from the service is returned in the BAPIURC field

Table 295 shows in more detail the return codes that can be returned to the caller (in register R15).

Table 295 CTMAPI Action Return Codes

Action AJF Allocations

For information on AJF Actions, see 3. AJF Actions.

Action Security Considerations

For information on AJF Action security considerations, see 3. AJF Actions.

Global Variable Extension

The Global Variable Extension is used to resolve, set, or checkpoint variables in the IOA Variable Database. For more information on this facility, see the IOA administration chapter in the INCONTROL for z/OS Administrator Guide.

The value for this function in the BAPICMD field is 6. For more information on the BAPICMD field, see CTMBAPI DSECT.

Table 296 contains a summary of the CTMBAPI Global Variable Extension input fields. You must ensure that all fields whose type is CL are initialized with BLANKS, and those with type X are initialized to binary zeros.

Table 296 Global Variable Fields

Global Variable Return Codes

Table 297 shows in more detail the Global Variable return codes that can be returned to the caller (in register R15).

Table 297 Global Variable Return Codes

Quantitative Resource Extension

The Quantitative Resource Extension function is used to query the status of a quantitative resource in the Control-M Resources file. It can be called from any environment by means of the CTMBAPI mode.

Use BAPI_M_RES to set the value for this function in the BAPICMD field to 4.

Table 298 CTMAPI Quantitative Resource Fields

Quantitative Resource Return Codes

The result is returned directly to the BAPI DSECT as specified below.

Table 299 CTMAPI Quantitative Resource Return Codes

Quantitative Resource Security Considerations

The security exit called is IOASE07.

Quantitative Resource Allocations

The files that are accessed, and the type of access, are summarized in Table 300.

Table 300 CTMAPI Quantitative Resource File Allocation

Zoom and Save from CTMAPI

To convert a job in the AJF to INP statements, use the following command:

BAPI_M_CNVINP  EQU    7            CONVERT AJF REC TO DEF

The calling program must provide the area where to return the INP definition.

To perform a Zoom and Save action, use the following command:

BAPI_M_ZOOM    EQU    8            ZOOM AND SAVE ACTION

In both cases, the requested RBA can be specified in either binary or character format. The calling program must provide the area where to return the INP definition.

The Zoom and Save process is executed as follows:

Begin

1. Call CTMAPI in order to search for the job using the SEARCH command, and retrieve its RBA.

2. Call CTMAPI to HOLD the job.

3. Call CTMAPI to convert the AJF records of the job to INP statements in which the necessary corrections will be made.

   Alternatively, the corrected job definition can be specified via BLT statements.

   The type of input (INP or BLT) is passed as one of the arguments to the Zoom and Save function.

4. Call CTMAPI to perform Zoom and Save action.

5. Call CTMAPI to FREE the job.

Create and/or Order or Force a Table (BLT)

The BLT function invokes the CTMBLT utility to create, save, and optionally order a table on the fly.

Unlike the other functions implemented through BAPI extension, this feature does not contain a separate extension where you define the input parameters. Instead

1. Set the BAPICMD field to the value BAPI_M_BLT.

2. Prepare the input to the API in memory as a regular CTMBLT input stream, as described in the INCONTROL for z/OS Utilities Guide, pointed to by the CTMCMDA field.

3. Set the length of the input, in bytes, in the BAPICMDL field. Each control input statement must be an 80-byte card image.

4. Set the reply fields.

   When requesting reply fields in this function, through the BAPI interface, you receive reply lines from both the CTMBLT function and CTMJOB. For more information on the reply input and output fields, see CTMBAPO.

BLT Action Return Codes

Table 301 BLT Action Return Codes

BLT Reply

The conversational mode (BAPI) BLT function can return a reply line for

• each Table that was saved

• each job that was processed

The reply line is mapped by the CTMBAPO DSECT, which is described in more detail in "CTMBAPO" on page 935.

BLT Security Considerations

When creating and saving tables, no IOA security exits are invoked to check the authority of the user to access the table. If the table must also be ordered, CTMSE01 will be called to verify that the user has the authority to order the table.

BLT Resource Allocations

Table 302 shows the files that are accessed, and the type of access.

Table 302 CTMAPI Quantitative Resource File Allocation

BAPI Replies

The BAPI feature returns output to the customer in the following ways:

• a return code

• setting output fields in the BAPI DSECT
  These fields were individually described in CTMBAPI DSECT.

• an output buffer returned by the Status service and described by the CTMBJSE DSECT

• the replies returned by the Order and BLT functions, as described in CTMBAPO

CTMBAPO

When in CTMBAPI mode, CTMAPI serves as an interface between a user program and a Control-M service. Some CTMAPI services have been modified to enable them to return lines of replies into customer-supplied memory to detail their activity. Currently this facility can be provided by

• the BLT process

• the Order process

For example, if the proper instructions are given, the Order process will return a reply line for each job which it processes. This contrasts with normal processing, where a line of output is not written until a job is actually placed on the AJF or a severe error has occurred. You can then act upon and/or process the reply lines.

To use this facility, you must supply the API with the pointers required to trigger the reply mechanism. These are supplied through the calling program. Table 303 shows the pointers and the fields in which they are supplied.

Table 303 CTMAPI Reply Mechanism Trigger Pointers

When BAPI returns, the BAPIRPLC field will point to the last byte actually written to the reply buffer, and the BAPIRPL# field will contain the number of lines put there. The API ensures that the value in the BAPIRPLC field never exceeds that set by the BAPIRPLE field. Each line added to the reply buffer will start with the current BAPIRPLC and will update it. BMC recommends that this field be initialized to zero. If this field is not zero, API treats the value as the starting address of the next reply line. This can be used by an application to accumulate reply lines across several invocations of CTMAPI.

Each line in the buffer is mapped by the CTMBAPO DSECT. Each line starts with a half-word that contains its length (BAPOLEN), and another two bytes that identify the service that produced the reply line (BAPOID). The identification of each reply line is mandatory, since a called service can call other Control-M services which, in turn, will place their reply lines in the buffer. By using the identification of each reply line together with the contents of the BAPIRPLC field and the BAPIRPL# field, you can code a routine to scan and filter reply lines.

Date Format Considerations

The format of all the date fields, both input and output, depends on your site standard. It follows that when you prepare the input to CTMAPI, you must know your site standard.