General Use Assembler Macros and Modules

This section describes the assembler macros, modules, and programs provided with INCONTROL products. Each macro, module, or program is described in detail in alphabetical order.

• CTMCOD Assembler Macro

• IOAENV Assembler Macro

• IOAMEM Assembler Macro

• IOABSR Program

• IOABSR64 Program

• IOASOR Program

CTMCOD Assembler Macro

The CTMCOD macro performs the following functions:

• extracts a code block from the MIT/MIC codes area

• writes a modified code block back into the MIT/MIC codes area

• adds a new code to the MIT/MIC codes area

Shown below are the environmental factors required for proper operation of the CTMCOD assembler macro:

• The CTMBCOD data area must be addressable to the program issuing the CTMCOD macro.

• Before invoking the CTMCOD macro, the issuing program must be in AMODE 31.

Syntax

CTMCOD Assembler Macro

name                   CTMCOD <function>
   ,CODE=requested code type                                   
   ,CONTIG=[Y/N]                                               
   ,MIT=address of MIT
   ,MCT=address of MCT
   ,NOTOK=label
   ,OK=label

Parameters

Table 316 CTMCOD Parameters

Output Register Information

When control returns to the caller from CTMCOD, the general purpose registers (GPRs) contain the following values:

Table 317 Output Register Information

Return Codes

Table 318 Return Codes from the CTMCOD INIT Function

Table 319 Return Codes from the CTMCOD GETNEXT Function

Table 320 Return Codes from the CTMCOD PUT Function

Table 321 Return Codes from the CTMCOD ADD Function

Table 322 User Abends

For an example of how to use the CTMCOD, see Sample Exit CTMX002H in the IOA SAMPEXIT library.

CTMCOD Programming Techniques

You can use the following programming techniques when working with the CTMCOD macro:

• You may need to update a certain code in the MIT after reading some other codes. For example, you must update MITCCPRE, the number of code values in an ON statement, after reading and counting all the code values in that block.

  To do this, save CTMBCOD fields CODPREVC, CODPREVL, and CODAMIC after reading the code to be updated, and then restore those values before the code is updated.

  The following sample code illustrates this technique:

  Copy

     CTMCOD GETNEXT,CODE=MITCCPRE
     MVC        KEEPPREC,CODPREVC
     MVC        KEEPPREL,CODPREVL
     MVC        KEEPAMIC,CODAMIC

  (read and process other codes)

  Copy

     MVC        CODPREVC,KEEPPREC
     MVC        CODPREVL,KEEPPREL
     MVC        CODAMIC,KEEPAMIC
     CTMCOD  PUT

  CODPREVC contains the address of the code that was read by CTMCOD GETNEXT. CODPREVL contains the length from this address until end of the MIC. CODAMIC contains the address of the MIC where the code resides. All these fields are used by CTMCOD PUT in order to locate the requested code and replace it with the value in CODOUTC.

• Programs that must read codes starting from a certain code, after other codes have been read and/or added, should also keep (and then restore) the values of fields CODCURRC and CODCURRL after the issuance of CTMCOD GETNEXT. These fields contain the address of the next code to be read after a code has been read, and the length from that address to the end of the MIC.

• When CTMCOD is used in a loop (for example, to go over all the codes of a certain type in a job), and for each loop iteration CTMCOD is used for other purposes, the following fields in CTMBCOD must be saved after the main loop's GETNEXT and restored after the internal CTMCODs:

  • CODPREVC

  • CODCURRC

  • CODPREVL

  • CODCURRL

  • CODAMIC

  • CODFUNC

IOAENV Assembler Macro

The IOAENV macro initializes the IOA environment by performing the following functions:

• Locate an area for the MCT and builds member IOAPARM into it.

• Provide parameters for dynamic allocation.

• Optionally build requested xxxPARMs.

• Optionally build requested xxxPLEXs.

• Optionally open LOG or LOG-in-Memory.

• Optionally initialize the messages environment, optional wishes environment, and trace options.

Syntax

The standard format of the IOAENV macro is shown below.

Syntax for IOAENV Macro

=============================================================================                                                    
name    symbol. Begin name in column 1. One or more blanks must precede IOAENV
IOAENV  One or more blanks must follow IOAENV
=============================================================================
INIT                          Build MCT.
SERV[,MCTADDR=field]          Add services/xxxPARMs.
REFR[,MCTADDR=field]          Refresh xxxPARM (except IOAPARM). Delete the loaded xxxPARM and load it again.
TERM[,MCTADDR=field]          Delete all loaded xxxPARMs and terminate all initialized services.
                              If MCTADDR is omitted, then we assume to have addressability for the MCT.
                              Note:  Only one MCT is handled by the macro. If it does not exist,then one is built.
,PARMS=     p                 Parameter letter.
           (p1,p2,..,pn)      Parameter letters.
           area               An area within the program that contains pairs of parameter letter and parameter suffix. For example:
                              area DC C’M3D5R8’,X’FF’
                              (use CTMPARM3; CTDPARM5; CTRPARM8)
                              Note: Each xxxPARM is loaded (with IOALDPRM) and it’s address is saved in the MCT. For IOA, CTM,
                              CTD, CTR and ECS the fixed part of the loaded xxxPARM is copied to the MCT.
,PLEX=      p                 xxxPLEX letter.
            (p1,p2,..,pn)     xxxPLEX letters.
            area              An area within the program that contains pairs of plex letter and plex suffix.
                              Note Each xxxPLEX is loaded (with IOALDPRM) and it’s address s saved ina table of addresses. 
                             The address of this table is saved in MCTPLEXT field.    
,CMEM=     YES/NO   If CMEM=YES then CMMPARM is loaded if Control‑O is NOT installed
,MSG=      YES/NO             Initialize the messages environment.
,WISH=     YES/NO             Initialize the optional wishes environment.
,TRACE=    YES/NO             Initialize trace options.
,LOG=      NO                 LOG not required.
           LOG                Open LOG.
           CHN                Open LOG-in-MEMORY for 500 records.
,MCT=      Rx                 Default: R12
                              NONE Unless MCT=NONE is coded, on return from INIT function the following commands are generated:
                              LR Rx,R1
                              USING MCTSTART,Rx
,LOC=      BELOW/ANY          Where all the GETMAIN(s) needed for the services will be done
,ERRET=    label              Label of error routine (see return codes).
                              If ERRET is omitted, an ABEND will be used.
,DUMP=     YES/NO             Isssue IOADUMP macro.
                              This macro issues ESTAE and prints mini-dump at ABEND time.
,ALLOC=                       (a1,a2,..,an) List of Allocation Member Names.
,FREE=                        (f1,f2,..,fn)List of Allocation Member Names.
,SP=       sp                  A one byte area containing the subpool number
                               If omitted, the default (132) is used
,RAREA=    area                Support area for PARMS/PLEX in reentrant programs.

Output Register Information

Table 323 Output Register Information

Extracting only the MCT address

If you want to extract only the MCT address, and do not require any other IOAENV functionality of the INIT function, use the GETMCT macro. GETMCT does not increase the use count of the IOAENV token.

The GETMCT macro has the following syntax:

GETMCT MCTREG=[register | NONE]

The MCTREG value determines the following behavior:

• MCTREG=NONE returns the MCT address in R1.

• MCTREG=register generates a USING statement, and the register will contain the MCT address.

The following return codes are available in R15:

IOAMEM Assembler Macro

The IOAMEM Assemble Macro module is a general purpose library– and member–handling program that can handle fixed or variable-length format libraries (of any record length). It transfers information from the library or member to memory, and back.

IOAMEM uses dynamic allocation, so usually no pre-allocation is required. However, IOAMEM can work on pre-allocated DD statements also, in which case the DD statements must be concatenated.

General Description

The IOAMEM module attributes are

RENT, AMODE=31 RMODE=24

Upon entry, the value of AMODE is saved. AMODE is set to 31 to handle addresses above the 16MB line. Upon return, the original value of AMODE is restored.

Storage for the handler is obtained below the 16 MB line and is saved in the handler address. The caller must not modify the handler address between the first call and the FINISH request call to module IOAMEM.

The handler address is returned in field IMHNDLR, which is mapped by macro IOAMMEM.

When invoking macro IOAMEM with parameter HANDLE=addr, the field that contains the handler address is not modified by macro IOAMEM. If more than one handler is used in the same program, save the handler address and invoke macro IOAMEM with the proper handler address in parameter HANDLE=addr.

It is not necessary to provide a buffer address for GETMEM, DIRECTOR, DIRALL, and DIRFULL requests.

If the buffer address is not passed (field value is zero), module IOAMEM obtains storage above or below the 16MB line. The number of records in the storage buffer is determined as follows:

• If field RECNUM (IMRECNUM) is not zero, then the number of records is the value in field RECNUM (IMRECNUM).

• If field RECNUM (IMRECNUM) is zero, then the default number of records is 5000.

The actual buffer size is the number of records in the buffer times the LRECL of the input dataset, plus 16 bytes for the header.

Module IOAMEM does not free any buffer the caller uses. If module IOAMEM obtains a storage buffer address on behalf of a caller, the caller must free this storage. The caller can free the buffer by using macro IOAXAGR. Field IMBUFARD points to the real buffer address + 16 bytes. The length of the buffer is in offset 4 from the beginning of the header.

If the buffer address is passed (field value is not zero), IOAMEM treats the value of IMRECNUM as the actual buffer size (in records). Therefore, to prevent storage protection violations, do NOT specify a value of IMRECNUM that exceeds the actual buffer size (in records).

If the buffer address is passed (field value is not zero) and the buffer size is insufficient, module IOAMEM ends with a return code of 08 and a reason code of 24. The actual number of records the member contains is returned in field IMRECNUM.

If the buffer address is not passed (field value is zero), module IOAMEM returns with a buffer that contains the entire member. The number of records in the buffer is returned in field IMRECNUM.

Macro IOAMEM checks whether parameter IOAMEMA has been supplied. If this parameter has been supplied, macro IOAMEM uses the supplied address. Otherwise, macro IOAMEM loads the IOAMEM module before invoking it and deletes it upon return.

GETMEM, GETLINE and PUTMEM requests support reading and writing members with record lengths other than 80 bytes. The GETLINE request can read members with variable record lengths.

The DIRECTOR, DIRALL, and DIRFULL functions accept a member name in the MEMBER sub-parameter of the IOAMEM macro. The member name may include masking characters. For example

MEMBER==CL8’*’

All members are included in the directory list (the same as a null MEMBER= parameter or MEMBER=0)

MEMBER==CL8'A?*'

All members that begin with the character A and have a total length of at least 2 characters are included in the directory list.

The DIRALL request provides similar functionality as the DIRECTOR function and additionally supports concatenated files for the given DD name. When DIRECTOR is used, each buffer entry length is 11 bytes — 8 bytes for the member name, and 3 bytes for the TTR. When DIRALL is used, each buffer entry length is 52 bytes — 8 bytes for the member name, and 44 bytes for the library name in which the member exists.

The FINISH request cleans up the environment, closes all opened DCBs, and frees all I/O buffers and the handler storage.

Module IOAMEM must be called with a FINISH request. Otherwise, some DCBs may remain open and some storage buffers may remain allocated.

When trying to access a DFHSM migrated dataset, IOAMEM will behave as follows:

• If the RECALL parameter was set to YES, access will be done with an automatic recall (all address spaces will wait until the dataset is recalled), and no further action will be required by the caller.

• If the RECALL parameter was set to NO (default), IOAMEM will decide what to do based upon the MCTENV flag. Note that the MCT address must be passed to IOAMEM (MCTADDR parameter).

  • If MCTENV is MCTENVSE (IOA online monitor) or MCTENV1 is MCTENVAS (IOA application server), then IOAMEM will submit a RECALL request to DFHSM and will return to its caller with RC=4 RSN=8 (see details of codes below). If, for some reason, the request fails, the regular RC is returned (RC=16 RSN=32).

  • If MCTENV is MCTENVON (IOA online session) or MCTENV is MCTENVKS (KSL environment) or MCTENV2 is MCTENVBU (CONTROL-B batch utilities), the behavior will be the same as if the RECALL parameter was set to YES, even when it was set to the default (NO).

The parameter list passed to IOAMEM is mapped by the IOAMMEM macro as follows:

Table 324 Mapping of Parameter List by IOAMMEM Macro

Table 325 Return Codes and Reason Codes

Table 326 Return Codes and Reason Codes (GETMEM, GETLINE, PUTMEM)

Table 327 Return Codes and Reason Codes (ALLOC, DEALLOC)

Table 328 Return Codes, Reason Codes and Descriptions

Table 329 Return Codes and Reason Codes from Librarian/Panvalet

Function Codes

The following function codes are supported by the IOAMEM module:

Table 330 Function Codes Supported by IOAMEM Module

To map the parameter list, use the IOAMEM macro with the following format:

[name]    IOAMMEM DSECT=[ NO | YES ]

To invoke the IOAMEM module, specify the IOAMEM macro with the following parameters:

IOAMEM Macro Parameters

[name] IOAMEM request,    Request type
       HANDLE=,           Handler address
       BUFFADR=,          Buffer address
       RECNUM=0,          Number of records in buffer
       FROMREC=0,         Read from record number
       MCTADDR=0,         MCT address
       DSNAME=,           DSNAME
       MEMBER=,           Member name
       USERID==CL8'IOAUSER',
                          User ID
       BUFFRMT=V,         Buffer format
       ACTION=A,          Action for PUTMEM
       ISPFSTAT=Y,        ISPF statistics for PUTMEM
       BUFFLOC=A,         Buffer location
       ESTAE=Y,           ESTAE request
       RECALL=N,          If HSM migrated, do nothing
       DUMP=N,            DUMP option when ESTAE is yes
       IOAMEMA=,          Location of IOAMEM address
MF=[ L | E | (E,label) ]

Table 331 Parameter Explanation

LOAD EP=IOAMEM ST R0,MEMADR
 
 IOAMEM GETMEM,
   DDNAME=0,    
               RECNUM=1000,                                        
               DSNAME==CL44'N22.LIB.CNTL',                           
               MEMBER==CL8'TESTX',                                   
               ESTAE=Y,                                              
               DUMP=N,                                               
               IOAMEMA=MEMADR,                                       
               MF=E,                                                 
               MCTADDR=0
 
         MVC   HANDLE,IMHNDLR save handler address
 
          IOAMEM GETMEM,                      
               HANDLER=HANDLE,                     
               BUFFADR=0,
               RECNUM=RECNUM,
               DDNAME=DDNAME,                                    
               DSNAME=DSNAME,                           
               MEMBER=MEMBER,                                   
               ESTAE=Y,                                              
               DUMP=N,                                               
               IOAMEMA=MEMADR,                                       
               MF=E,                                                 
               MCTADDR=0
 
HANDLE   DS      A  
DDNAME   DC     CL8’DD1’
DSNAME   DC     CL44’MY.DSNAME’
MEMBER   DC     CL8’MEMBER1’
RECNUM   DC     A(10000)

IOABSR Program

IOABSR is a general-purpose program that manages internal (that is, in-memory) tree-structured lists of keyed records. Every record consists of a variable-length key and a variable-length data field.

The IOABSR program performs very fast additions and updates of records in the tree, as well as extractions of records into a caller area. As the tree is kept balanced, the maximum path length to the target record requires checking log₂N elements, where N is the total number of records kept in the tree.

You can use the IOABSR program, for example, in Control-M AutoEdit processing, where an AutoEdit variable name is used as the key and the value is the data.

IOABSR Attributes and Fields

The IOABSR load module attributes are

RENT, AMODE=31 RMODE=24

Upon entry, the value of AMODE is saved. AMODE is set to 31 to handle addresses above the 16MB line. Upon return, the original value of AMODE is restored.

Use the following call statement to invoke the IOABSR program:

CALL ioabsr,(interface_blk,function,key_length,data_length)

Table 331a Fields for Invoking the IOABSR Program

<key_length>    DS    H
<key_body>      DS    XL(max key_length)                        

<data_length>   DS     H
<data_body>     DS     XL(max data_length)             

IOABSR Return Codes

The following codes are returned in Register 15 (R15) and also in the first half of the 11th word of interface_blk:

Table 331b Return Codes from the IOABSR Program

IOABSR Example

The following example presents a call to the IOABSR program:

. . .
         CALL  IOABSR,(BSRDSC,BSRFUNC,BSRKEYL,BSRDATL)
. . .
BSRDSC    DS     16F
BSRFUNC   DS     CL4
BSRKEYL   DS     H
BSRKEY    DS     XL(max key_length)
BSRDATL   DS     H
BSRDATA   DS     XL(max data_length)

IOABSR64 Program

The IOABSR64 program is very similar to the IOABSR program, with the following differences:

• IOABSR64 keeps the tree in the storage located above the bar.

• The first IOABSR64 parameter must point to a 40F (20D) area that is used by IOABSR64 as a work area.

• The length of the KEY (as well as the length of the DATA) is limited to 32760 bytes in IOABSR64.

IOABSR64 Parameters

The area that the first parameter points to can be described as follows:

WORKAR   DC    40F'0'
         ORG   WORKAR
BASESIZE DS    F                     
RETCODE  DS    H                     
RSNCODE  DS    H                     
@TOTSIZE DS    2F         TOTAL SIZE OF OBTAINED MEMORY (in bytes)               
@DEADSIZ DS    2F         TOTAL SIZE OF DEAD MEMORY (FRAGMENTATION)   
@TOTENT# DS    F          CURRENT TOTAL NUMBER OF ENTRIES IN THE TREE 
         DS    8F                     
BSRTREEA DS    F'0'       PTR TO THE TREE HEADER  
         ORG   ,     

Note the following parameters and fields:

• IOABSR64 returns the @TOTSIZE, @DEADSIZ, and @TOTENT# fields on every call of RC=12 or less.

• BASESIZE: Defines the size of the memory object that is obtained every time that additional memory is needed, in megabytes. The default is 1 megabyte.

• BSRTREEA: Defines a pointer to the tree header. Initially it must be 0. IOABSR64 returns the value when it creates the tree.

IOASOR Program

IOASOR is a general-purpose SORT program that sorts vectors in the memory. The following limitations enable the IOASOR program to achieve exceptionally high performance:

• The record length and key length are both limited to 256 bytes.

• The vector is sorted by one key only.

IOASOR Attributes and Fields

The IOASOR load module attributes are

AMODE=31 RMODE=31

Use the following call statement to invoke the IOASOR program:

CALL  (ioasor),(vector,no_of_entries,entry_length,key_position,ascend/descend_and_keylen)

Table 331c Fields for Invoking the IOASOR Program