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

  Field Name	Optional or Mandatory	In or Out	Type	Usage
  BAPICMD	O	I	CL1	One byte identifier of the requested service
  				Note: If the BAPICMDA field is set to a value other than zero, it takes precedence over the BAPICMD field.
  BAPICMDA	O	I	A	Address of command buffer. The command syntax should be identical with the syntax of the individual CTMAPI functions described in this appendix. If set to zero, the requested service must be specified in the BAPICMD field.
  BAPICMDL	O	I	F	Length of the command in the command buffer. Ignored if the value in BAPICMDA is zero.
  BAPIFLG1	O	I	Flag	General purpose flag. BAPIF1CN (X’80’) – Do not release the working area on return. Applicable for programs that call the API several times. It is the responsibility of the caller to call the API with the function BAPI_TERM to allow the API to free storage, close files, and so on. Failure to do so may cause unpredictable results, such as storage accumulation.
  BAPIMCT	M	I or O	A	Address of IOA MCT used by the API. The caller must set this field to zero on the first call, and leave it untouched between multiple calls.
  BAPIRC	Not applicable	O	H	Return code returned to the caller. Identical with register R15.
  BAPIRPL#	O	O	F	Number of reply slots returned by the API. The size of each slot depends on the service requested.
  BAPIRPLC	O	O	F	Address of the first free byte in the reply area. Serves to indicate the end of that area.
  BAPIRPLE	O	I	A	End address of the reply buffer. If BAPIRPLS (in this Table) is set to zero, this field is ignored. This field informs API of the size of the reply buffer. In some services, such as STATUS, if the reply buffer space is exhausted, a special return code indicating this is returned to the caller. The caller can then again call the API to obtain the rest of the reply.
  BAPIRPLS	O	I	A	Start address of the reply buffer. If set to zero, no reply is returned. If set to a value other than zero, the API returns its replies into this buffer. The reply that the API can return is explained in relation to each service.
  BAPIRSN	Not applicable	O	H	Reason code returned to the caller. Valid reason codes are documented internally in the CTMBAPI macro.
  BAPISIGN	M	I	CL4	DSECT eye-catcher ‘BAPI’
  BAPIURC	Not applicable	O	H	Return code returned to CTMAPI from the invoked utility if that utility failed. This return code is set only if CTMAPI ended with return code 8. Otherwise, the CTMAPI return code itself identifies the problem.
  BAPIVERS	M	I	CL1	DSECT Version. The current version is 1.
  BAPIWORK	M	I or O	A	Address of the API work area. This field is used by the API to hold information between calls when more replies must be returned. The caller must set this field to zero and leave it untouched between multiple calls.