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.