REXXTDLI calls

The following information describes usage considerations for REXXTDLI calls.

Format

Read syntax diagramSkip visual syntax diagram dlicall parm1 parm2 ...

The format of a DL/I call varies depending on call type. The parameter formats for supported DL/I calls can be found in DL/I calls for database management, DL/I calls for transaction management, and DL/I calls for IMS DB system services. The parameters for the calls are case-independent, separated by one or more blanks, and are generally REXX variables. See Parameter handling for detailed descriptions.

Return codes

If you use the AIBTDLI interface, the REXX RC variable is set to the return code from the AIB on the DL/I call.

If you do not use the AIBTDLI interface, a simulated return code is returned. This simulated return code is set to zero if the PCB status code was GA, GK, or bb. If the status code had any other value, the simulated return code is X'900' or decimal 2304.

Parameter handling

The IMS adapter for REXX performs some parameter setup for application programs in a REXX environment. This setup occurs when the application program uses variables or maps as the parameters. When the application uses storage tokens, REXX does not perform this setup. The application program must provide the token and parse the results just as a non-REXX application would. For a list of parameter types and definitions, see Table 1.

The REXXTDLI interface performs the following setup:

  • The I/O area retrieval for the I/O PCB is parsed. The LL field is removed, and the ZZ field is removed and made available by means of the REXXIMS('ZZ') function call. The rest of the data is placed in the specified variable or map. Use the REXX LENGTH() function to find the length of the returned data.
  • The I/O area building for the TP PCB or alternate PCB is done as follows:
    • The appropriate LL field.
    • The ZZ field from a preceding SET ZZ command or X'0000' if the command was not used.
    • The data specified in the passed variable or map.
  • The I/O area processing for the SPA is similar to the first two items, except that the ZZ field is 4 bytes long.
  • The feedback area on the CHNG and SETO calls is parsed. The LLZZLL fields are removed, and the remaining data is returned with the appropriate length.
  • The parameters that have the LLZZ as part of their format receive special treatment. These parameters occur on the AUTH, CHNG, INIT, ROLS, SETO, and SETS calls. The LLZZ fields are removed when IMS returns data to you and added (ZZ is always X'0000') when IMS retrieves data from you. In effect, your application ignores the LLZZ field and works only with the data following it.
  • The numeric parameters on XRST and symbolic CHKP are converted between decimal and a 32-bit number (fullword) as required.
Table 1. IMS adapter for REXX parameter types and definitions
Type1 Parameter Definition
PCB
PCB identifier specified as a variable containing one of the following:
  • PCB name as defined in the PSB generation on the PCBNAME= parameter. See IMS Version 15.5 System Utilities for more information on defining PCB names. The name can be from 1 to 8 characters long and does not have to be padded with blanks. If this name is given, the AIBTDLI interface is used, and the return codes and reason codes are acquired from that interface.
  • An AIB block formatted to DFSAIB specifications. This variable is returned with an updated AIB.
  • A # followed by PCB offset number (#1=first PCB). Example settings are:
    • IOPCB=:"#1"
    • ALTPCB=:"#2"
    • DBPCB=:"#3"
    The IOAREA length returned by a database DL/I call defaults to 4096 if this notation is used. The correct length is available only when the AIBTDLI interface is used.
Important: The PCB parameter is not required if the REXXTDLI interface is used for making a synchronous callout request (ICAL call). Instead, the keyword DFSAIB must be specified before the input and output parameters.
In Input variable. It can be specified as a constant, variable, *mapname2, or !token3.
SSA Input variable with an SSA (segment search argument). It can be specified as a constant, variable, *mapname2, or !token3.
Out Output variable to store a result after a successful command. It can be specified as a variable, *mapname2, or !token3.
In/Out Variable that contains input on entry and contains a result after a successful command. It can be specified as a variable, *mapname2, or !token3.
Const Input constant. This command argument must be the actual value, not a variable containing the value.
Note:
  1. The parameter types listed in IMS adapter for REXX parameter types and definitions correspond to the types shown in Summary of DB calls, Summary of TM message calls, and Summary of system service calls, as well as to those shown in REXXIMS extended commands.

    All parameters specified on DL/I calls are case independent except for the values associated with the STEM portion of the compound variable (REXX terminology for an array-like structure). A period (.) can be used in place of any parameter and is read as a NULL (zero length string) and written as a void (place holder). Using a period in place of a parameter is useful when you want to skip optional parameters.

  2. For more information on *mapname, see MAPGET and MAPPUT.
  3. For more information on !token, see STORAGE.

Issuing synchronous callout requests

To issue a synchronous callout (ICAL call) request using the REXXTDLI interface, you must specify the DFSAIB keyword followed by the input and output areas. Both the input and output areas can be specified as a variable, *mapname, or !token.

The syntax for the ICAL call from the REXXTDLI interface is:

Read syntax diagramSkip visual syntax diagram ICAL DFSAIB In Out

A default length of 1024 bytes will be passed as an input to the AIBOAUSE field for undefined or implicit variables in the output area. To specify larger messages, you will need to issue the STORAGE command.