APIDSECT Fields

The following table lists the APIDSECT fields:

Field Description
API_SERVER_TYPE Defines the method of communicating with the Platform Server for z/OS started task.

This field is required.

You must enter one of the following values:

  • API_SERVER_TYPE_PCCALL

    Communicate through cross memory by using a PC call.

    Note: The API program must be executing on the same LPAR for PCCALL communications to work.
  • API_SERVER_TYPE_SNA

    Communicate through SNA.

    When communicating through SNA, the client program can execute on any machine that has SNA connectivity between the client program and the Platform Server started task.

  • API_SERVER_TYPE_IPADDR

    Communicate through TCP by using an IP address.

    When communicating through IP address, the client program can execute on any machine that has TCP connectivity between the client program and the Platform Server started task.

  • API_SERVER_TYPE_IPNAME

    Communicate through TCP by using an IP name.

    When communicating through IP name, the client program can execute on any machine that has TCP connectivity between the client program and the Platform Server started task.

API_SERVER_TRACE_FLAG Defines whether to trace the communication with the Platform Server started task.

This field is optional. If not entered, not tracing is used.

If tracing is set to API_SERVER_TRACE_YES for SNA communication, the VTAMTRAC DD statement must be defined. If tracing is set to API_SERVER_TRACE_YES for IPADDR or IPNAME communication, the TCPTRAC DD statement must be defined.

Note: This option is ignored for PCCALL communication.
API_OUTPUT_DCB_ADDR Defines the address of an open DCB that is to be used by the API program to write output about the request.

This field is required.

The DCB must have the following attributes:

RECFM=FBA

LRECL=133

MACRF=PM

Note: The calling application is responsible for opening and closing this DCB.
Note: If API_OUTPUT_DCB_ADDR is NULL, the API program does not write any data to it. Error messages are displayed on the console. While this flag works for any request, it should be used only on a PING request.
API_SERVER_FLAG_SILENT When this flag is set, the API program does not write any output. It also does not display any error messages on the console. While this flag works for any request, it should be used only on a PING request.
API_OUTPUT_DDNAME

When API_OUTPUT_DDNAME_ADDR is set to 0x00000000, this field is ignored. When API_OUTPUT_DCB_ADDR is set to a value other than 0x00000000, the output data is written to the DD name pointed to by this parameter.

This parameter is only used when API_OUTPUT_DCB_ADDR is set to 0x00000000.

You must specify the following field when API_SERVER_TYPE_PCCALL is defined:

Field Description
API_SERVER_STCNAME Defines the name of the Platform Server z/OS started task.
Note: When using API_SERVER_TYPE_PCCALL, the Platform Server started task must be executing on the same LPAR as the API program.

You can specify the following fields when API_SERVER_TYPE_SNA is defined:

Field Description
API_SERVER_LUNAME Defines the name of the Platform Server for z/OS started task VTAM APPLID.

This field is required.

API_SERVER_ACBNAME Defines the name of the VTAM ACB that is defined for use by the Platform Server API programs.

This field is required.

If this ACB name includes 6 characters or less, the Platform Server attempts to add a 2-digit numeric suffix to the ACB name. In this way, multiple API requests can use the same API_SERVER_ACBNAME value. A typical installation creates ACB definitions for the Platform Server clients with a name such as FUSN00 - FUSN09, thus supporting 10 concurrent connections.

API_SERVER_MODENAME Defines the VTAM mode name that is to be used for the connection.

This field is optional.

If not defined, the mode name associated with the VTAM definition is used.

You can specify the following fields when API_SERVER_TYPE_IPADDR is defined:

Field Description
API_SERVER_IPADDR Defines the IP address in EBCDIC dotted decimal format of the machine where the Platform Server started task is executing.

This field is required.

API_SERVER_TCIPJOBNAME Defines the name of the TCP/IP started task.

This field is optional. If not defined, the value TCPIP is used.

API_SERVER_IPPORT Defines the 5-digit EBCDIC decimal IP port that is to be used to connect to the Platform Server started task.

This field is optional. If not defined, the default Platform Server port value of 46464 is used.

You can specify the following fields when API_SERVER_TYPE_IPNAME is defined:

Field Description
API_SERVER_IPNAME Defines the 64-digit IP name of the machine where the Platform Server started task is executing.

This field is required.

API_SERVER_TCIPJOBNAME Defines the name of the TCP/IP started task.

This field is optional. If not defined, the value TCPIP is used.

API_SERVER_IPPORT Defines the 5-digit EBCDIC decimal IP port that is to be used to connect to the Platform Server started task.

This field is optional. If not defined, the default Platform Server port value of 46464 is used.

Execute Transfer Parameters

The following input parameter and output parameter are used when executing the Platform Server transfers:

Field Description
API_TRANSFER_PARM_ADDR Defines the parameter cards that is to be passed to the Platform Server API program.

The parameters are identical to the parameters that are accepted by the Platform Server Batch interface. Comments can be placed in the parameter list by starting the parameter with an asterisk (*). However, comments are not allowed in the first parameter.

The parameters are passed to the API using the following format: llll, which indicates length in bytes of the parameter passed. The length does not include the 2-byte length field.

The first parameter passed must be one of the following parameters:

  • PROCESS,,TRANSFER,SEND: To send a file.
  • PROCESS,,TRANSFER,RECEIVE: To receive a file.
  • PROCESS,,PING: To receive a status.

The parameter stream ends with a parameter that has a length of 0x0000.

Note: Parameters are passed directly to the Platform Server Batch Interface program. Therefore, the API has the same restrictions as the Batch interface regarding continuation. Data is accepted in columns 1 - 71. Column 72 is used for continuation. Columns 73 and above are ignored. In addition to using column 72 as a continuation column, you can use the special Batch continuation characters: plus sing (+) and double plus signs (++).
API_TRANSFER_ID This parameter is returned by the started task when a transfer is queued successfully or executed either successfully or unsuccessfully.

The transfer ID is not returned under the following circumstances:

  • An APIDSECT parameter is filled in incorrectly.
  • A transfer parameter is invalid.
  • The API program cannot connect to the Platform Server started task.
  • A send transfer is requested, but the file does not exist.
  • You request a user profile, but the profile does not exist.

Transfer Status Parameters

The following input parameter and output parameter are used when executing the Platform Server transfers:

Field Description
API_TRANSFER_PARM_ADDR Defines the parameter cards that is to be passed to the Platform Server API program.

The parameters are passed to the API using the following format: llll, which indicates length in bytes of the parameter passed. The length does not include the 2-byte length field.

The following two parameters are required:

  • PROCESS,,OPERATE
  • TRNSTATUS=tttttttttt

    tttttttttt is the transfer ID of a file transfer.

The parameter stream ends with a parameter that has a length of 0x0000.

API_TRANSFER_STATUS This field is returned by the Platform Server and defines the transfer status of the transfer specified in the TRNSTATUS parameter.

This is an 8-byte character field left aligned and padded with spaces.