gtpg2m0cGeneral Macros

Macro Usage Conventions

This section provides additional programming considerations and general use information on selected groups of commonly used macros. This information complements the detail specifications in the remainder of the publication.

In the years when TPF was confined below the 16M line, addresses were 24 bits long. Since words and registers were 32 bits long, sometimes the extra 8 bits were used improperly for non-addressing purposes. With the advance of addressing past the 16M line the extra bits can be easily misinterpreted, giving incorrect results. In particular, some macros can return incorrect results if addresses passed to them have their high order bit (X'80') set. The technique of loading a zero address; such as,

LA Rx,0(Rx)

before a macro call clears out registers in the way required.

A note about severity codes for macros. Some conditions warrant attention from users. Usually these conditions are errors, however, sometimes they are informational comments. Error severities range from 4 (for the least severe) to 12 (for the most severe). Informational comments are listed with a severity of *.

BEGIN and FINIS Macros

The BEGIN and FINIS macro instructions must be used as the first and last source statement, respectively, in any assembler language ECB-controlled program. These macros generate header information in assembled object code. The header is used by the system allocator and system loader to load the programs to the TPF system online modules from the loader general file. This header represents a system record to different initialization procedures.

Note:
Many of the executive macros depend on various fields in the ECB. Therefore, it is very useful for the programmer to have detailed knowledge of this control block prior to reading this publication.

Enter-Back Macros

The Enter-Back macros provide the facility for ECB-controlled (also referred to as E-type) programs to transfer control to other E-type programs. The control program performs the processing necessary to transfer control, including any I/O operations.

The E-type programs can reside on direct access storage devices (DASDs), in VFA buffers, or in main storage.

If the program to which control is to be transferred is resident on an external storage device, a Read operation is performed to retrieve the program. While the Read operation is taking place, the control program can give control to another ECB if one is ready for processing (implied Wait).

A program can request transfer of control to another program by issuing a kind of Enter-Back macro. The following requests can be made:

The transfer of the information required by the control program to locate and invoke a requested program is accomplished using the Enter-Back macro expansions.

In general, the macro expansions contain:

The resolution of the macro expansions is performed in two stages. The first stage takes place when the issuing program is assembled. At that time, space is reserved in the program for the macro expansion by V-type constants (V-CONS). The V-CONS not only reserve space, but the label that is used identifies the type of macro and the name of the requested program (see the ENTRC, ENTNC, ENTDC, and BACKC macro descriptions).

The second stage occurs when the issuing program is selected for loading to the Loader General File. At this time the Linkage Editor program is invoked to resolve the V-CONS contained in the program to be loaded. The Link Editor program uses the contents of the program allocation table (PAT), which is a directory of all of the system's E-type programs, to determine the type of residency of both the requesting and requested program. The address of the requested program is also obtained from the PAT. Using the data from the PAT, the Link Editor program fills in the Enter-Back macro expansions.

There are several classifications of the E-type programs. Programs that are allocated to reside on DASD devices are referred to as file-resident programs. E-type programs can also be allocated to reside in main storage. Programs allocated to main storage are classified as core resident programs.

Main Storage Allocation Macros

Main storage can be obtained and ultimately released in any of the following ways.

When an operational program executes a GETCC macro, the control program will assign one main storage block of the specified storage size to the entry control block. Reference to the main storage block is placed in the core block reference word for the specified level.

The RELCC macro allows the operational programs to release main storage blocks after they are no longer needed. The control program returns the main storage block (referenced in the core block reference word) to the working storage pool when an RELCC is executed. Only one main storage block can be returned at a time. Main storage blocks should be released as soon as possible by the user program.

In general, an operational program should use a GETCC macro to obtain a main storage block in which a data record or message is to be created. Following creation of a message or data record, a File or Send type macro is used to transmit the data to auxiliary storage or over a communication line.

Use care when using these macros. To allow for efficient utilization of main storage, return blocks as soon as they are no longer required by the user program. The control program releases all blocks held by an entry when the entry exits.

File Storage Allocation Macros

A file pool storage record address can be obtained by executing a GETFC macro for a 4KB, large, or small record respectively. The file pool record address is placed in the file address reference word (FARW) of the data level specified in the macro statement.

For GETFC, the record ID implies an index into the RIAT (DCTRIT) table from which record attributes are obtained.

The basic file pool types optionally available in a system include:

Where x is A, B, C, or D and indicates that the pool types are distinguished by the TPF system devices (that is, DEVA, DEVB, DEVC, and DEVD).

Pools 1, 2, 4, 5, 7, and 8 will contain single copy records in a partially duplicated file system and duplicate records in a completely duplicated file system. Pools 3, 6, and 9 are provided for systems with a partially duplicated file system and a requirement for duplicate file pool storage records.

All file pool record addresses must be returned by executing a RELFC macro. The file address reference word (data level) containing the address that is being returned is specified as a parameter of the RELFC macro. Short-term pool addresses are, in effect, immediately returned to the relevant pool for reuse. Consequently, short-term pool records can be used to store different records during a short interval of time. Long-term pool ordinals and records are stored in a return block that is written to a Real-time tape for offline processing. The returned long-term addresses can be kept out of the online system for several days.

It is suggested that the short-term pools be used for storing records that are maintained for short intervals of time (for example, the time required to complete a reservation transaction with a customer). The short-term pools are designed for quick turnover records. Long-term file pool records can be maintained during an interval of time as dictated by operational procedures.

The basic file pools previously mentioned can be split across more than one external storage device type. Each split is called a pool section. The selection of a pool section is normally based on the record ID in the RIAT for the GETFC macro. Ratio dispensing/pool fallback can modify normal pool selection as described later.

The following sample macro statement will be processed as described:

CVEDXX   GETFC D2,,CW

  1. Assembler Program
    CVEDXX   DC    VL3 (CWL#Z6)
             DC    AL1 (D2)
    
  2. Link Editor Program

    Record ID CW is assigned the following characteristics:

    Based on the these assumptions, the VL3 will be resolved as follows:

    Byte Value  
    0 0A SVC Code
    1 2 LLT pool
    2 04 DEVA (DASD)

    The GETFC macro expands as follows:

    Byte Bit Contents
    0      SVC
    1      GETFC INTERRUPTION CODE
    2 0 = 0 RECORD ID IN MACRO EXPANSION
        = 1 RECORD ID IN SPECIFIED REGISTER
      1 = 0 PRIME RECORD ATTRIBUTE
        = 1 OVERFLOW RECORD ATTRIBUTE
      2 = 0 DON'T GET CORE BLOCK
        = 1 GET CORE BLOCK
      3 = 0 SYSTEM ERROR IF INVALID REC ID
        = 1 RETURN IF INVALID RECORD ID
      4-7        SPECIFIED REGISTER (IF BIT 1 ON)
    3      DATA LEVEL INDEX
    4,5      HEXADECIMAL REC ID (IF BIT 1 OFF)

GETFC has an implied Wait. When a Get File Storage request cannot be immediately serviced, further processing of the entry requesting the file address is postponed. A file pool directory is reordered when an active directory reaches a predefined critical level of available addresses. The implied Wait is applied to a Get File Storage macro when the appropriate file pool directory is depleted of available addresses. This allows processing of other entries in the system.

All file storage addresses should be returned as soon as possible with a RELFC macro. A file storage address must be released only once. If a short-term double release occurs, a system error dump is taken. Control is then returned to the operational program that executed the RELFC macro.

Ratio dispensing is used to dispense addresses for a specific basic pool type using several sections of the pool. As each pool section is selected, its ratio number (that is, the number of addresses) is used to determine how many addresses to dispense from that section before selecting another pool section.

File pool fallback allows alternate pool sections with like records (that is, small or large, duplicate or single copy) to be used to satisfy GETFC requests to depleted pool sections. Short-term pool sections can fall back to short-term or long-term pool sections. Long-term pool sections can fall back only to other long-term pool sections with like records.

Ratio dispensing and pool fallback are available for pool sections. The schedules used to control this function are initialized based on optional SYCON parameters or commands. See TPF Database Reference for more information about ratio dispensing and pool fallback.

File Type Macros

The file macros allow the user programs to Read (Find), Write (File), and Hold a file record. They consist of the following:

FDCTC
File Data Chain Transfer

FILEC
File A Record

FILSC
File A Single Record

FILUC
File A Record And Unhold

FILNC
File A Record And No Release

FINDC
Find A File Record

FINHC
Find A File Record And Hold

FINSC
Find A Single File Record

FINWC
Find A File Record And Wait

FIWHC
Find A File Record Hold And Wait

FLSPC
File A Special Record

FNSPC
Find A Special Record

UNFRC
Unhold File Record.

Operational programs address file records by supplying a reference record identification (ID) and a pseudo file address in a file address reference word (FARW). Each record ID field is contained in 4 bytes of main storage in the ECB. Each record ID field in a data event control block (DECB) is contained in 4 bytes of main storage (like an ECB) and the file address field is 8 bytes (for a total of 12 bytes of main storage).

The format of the record ID field is as follows:




The record type identifies the general type of the record requested (such as inventory and passenger name index). The record code check (RCC) is a unique number generated by the operational programs and is used by the control program to verify the integrity of records. The following describes the various requirements and checks made by the control program.

File Macros

  1. If the RCC = 0, no verification is made by the control program. If the RCC = nonzero, the control program compares the RCC fields in the ECB or DECB to that of the record to be filed. If the comparison fails, a system error is generated and the ECB is exited.
  2. The record type must always be supplied and can never be zero. The control program compares the record type field in the ECB or DECB to that of the record to be filed. If the record type is zero or the comparison fails, a system error is generated and the ECB is exited.

Find Macros

  1. If the RCC = 0, no verification is made by the control program. If the RCC = nonzero, the control program compares the RCC field in the ECB or DECB and the record that was read. If the comparison fails, the appropriate system error bits (CE1SUD, CE1SUG in the ECB, or IDECSUD in the DECB) are set. No system error is generated and return is made to the user program following WAITC processing.
  2. If the Record Type = 0, no verification is made by the control program. If the Record Type = nonzero, the control program compares the record type field in the ECB or DECB and the record that was read. If the comparison fails, the appropriate system error bits (CE1SUD, CE1SUG in the ECB, or IDECSUD in the WAITC processing.
    Note:
    Each of the 16 data levels in an ECB has a detailed error indicator (CE1SUD). In addition, there is a gross data level indicator (CE1SUG), which represents the cumulative error indicator for all the data levels. With TPF DECB support, each DECB has a detailed error indicator (IDECSUD). The existing gross data level indicator (CE1SUG) accounts for any errors that occurred on a DECB-related I/O operation. Therefore, it is not necessary to have a separate gross indicator for TPF DECB support. When an error occurs for a DECB, bit IN1DUD in the ECB indicator byte (CE1IN1) is turned on.

See TPF Database Reference for more information about the formats of the TPF file addresses. The format of the file address is determined by the type of FIND/FILE macro issued and the value of the GDS keyword specified on the FIND or FILE macros. For example, a FNSPC or a FLSPC macro supports only a hardware address format of module number (MM), cylinder number (CC), head number (HH), and record number (R), whereas a FINDC macro can be used to access general files, general data sets and the online database. The file address format is determined by the GDS keyword on the FINDC macro. In TPF3, the code to handle a FIND or FILE for a GDS or GF checked two places to differentiate between a normal FARF3 SON or a GDS or GF file address format. In TPF4, the GDS parameter must be set to YES to distinguish between FARF3 SON addresses and general file or general data set addresses. Earlier versions of TPF did not require this. Not doing so, even in FARF3 systems, can cause addressing failures.

Duplicate Operations

The control program examines the file address and, following the execution of a Write (FILEC) macro, both the primary and duplicate record will be updated automatically if both exist. Likewise, following the execution of a Read (FINDC) macro, the control program will retrieve the alternate record if the primary record cannot be successfully read. Only if neither the duplicated nor the primary record is found will an error be posted.

Occasionally, it is necessary for a program to selectively read or write only the primary or duplicate record. A set of unique macros (FINSC, FILSC) is provided for this purpose, and unlike other file macros:

  1. They should be used only to access records from the online database.
  2. Only the specified record (primary or duplicate) is updated following execution of Write single.
  3. Only the specified record (primary or duplicate) is retrieved following execution of Read single.

Holding a Record

The record hold feature is a method of reserving data for exclusive use of a program during the updating of that record. When a Hold macro is used, the Record Hold Table is checked to determine if the record is being held for a previous request. If the record is not being held, the file address of the record is placed in the Record Hold Table and the request is serviced. If a previous request is holding the required record, the current request is not serviced until the record is unheld by the previous entry. All record hold requests are serviced on a first-come, first-served basis.

When executing a Find a File macro (FINDC), it is possible to access a record that is currently being held and to update it. The Record Hold Table is checked only when servicing a Find and Hold (FINHC, FIWHC) macro.

Note:
Therefore, it is imperative that all programs updating records observe the convention of using a Find and Hold macro to retrieve the record to be updated. The TPF control program does not enforce this convention.

An entry should hold only one record at a time. This is necessary to avoid a condition where two entries are each waiting for a record that the other is holding. A record can be unheld by executing an Unhold macro (UNFRC, FILUC). A held record must be unheld before processing of the entry is completed.

It is important to recognize that running any write File macros (except FILNC) will cause the ECB data level or DECB containing the main storage block to return to the available storage pool after completing the write operation. In addition, the data block is detached from the entry at macro processing time. Accordingly, following the running of any File macro (except FILNC), the data level or DECB is available on return from the control program even though the write operation can be completed.

General Data Set Macros

The General Data Set Name (GDSNC) and General Data Set Record (GDSRC) macros are used to access general data set records. GDSNC is used to open and close the data set. GDSRC is used to access specific records in the data set. The Find and File type macros are used to read from and write to the data set.

You must open the data set by passing the name, volume sequence number, and relative record number (RRN) of the data set with the GDSNC macro. The volume sequence number and RRN can be zero. GDSNC returns the indexes necessary for the system to access the data set that the user specified with the macro (in fields CE1FMx, CE1FCx, CE1FHx, and CE1FRx of the ECB data level or fields IDECFM, IDECFC, IDECFH, and IDECFR of the DECB). The file address of the RRN in the data set is returned in CCHR format in the file address extension word (FAXW) (field CE1FXx for the ECB data level or field IDECFX0 for the DECB). If the RRN was zero, the address of the first record of the data set is returned.

To access specific records in the data set the user must pass the RRN of the desired record with the GDSRC macro. The RRN can be zero. GDSRC returns the file address of the desired record in the FAXW (CE1FXx for the ECB data level or IDECFX0 for the DECB) in CCHR format. If the RRN specified was zero, the address of the first record of the data set is returned.

The Find or File macros (FDCTC, FILEC, FILNC, FILUC, FLSPC, FINDC, FINHC, FINWC, FIWHC, FNSPC, UNFRC) are used to read data from, or write data to, the general data set record. You can set up the FARW (CE1FAx for the ECB data level or IDECFRW for the DECB) with the record ID and RCC. The file address was already set up by the GDSNC and GDSRC macros.

After managing the data with the Find and File macros, you must close the general data set with the GDSNC macro. The parameters passed are the same as those passed with GDSNC open. The FARW (fields CE1FMx, CE1FCX, CE1FHx, CE1FRx for an ECB data level or fields IDECFM, IDECFC, IDECFH, and IDECFR for a DECB) is cleared on return from GDSNC close.

An example of the use of the General Data Set macros follows:

***********************************************************************
* "OPEN" THE GENERAL DATA SET.                                        *
***********************************************************************
         XC    CE1FM8(1),CE1FM8      VOLUME SEQUENCE NUMBER
         MVC   EBW000(16),=CL16'TPF.DATA.SET.A'  DATA SET NAME
         MVC   EBW016(4),=F'0'       RELATIVE RECORD NUMBER
         LA    R14,EBW000            ADDRESS OF DATA SET NAME
         GDSNC D8,O,RCT=A,SIZE=L,WORK=YES  OPEN DATA SET
         LTR   R14,R14               CHECK RETURN CODE
         BNZ   GDSNERR               BRANCH IF ERROR
***********************************************************************
* READ, UPDATE, AND WRITE THE FIFTH RECORD OF THE GENERAL DATA SET.   *
* WHEN WORK=YES THE USER MUST PASS THE RELATIVE RECORD NUMBER IN THE  *
* FOUR BYTES IMMEDIATELY FOLLOWING THE DATA SET NAME.                 *
***********************************************************************
         LA    R14,EBW000            ADDRESS OF DATA SET NAME
         MVC   EBW016(4),=F'5'       RELATIVE RECORD NUMBER = 5
         GDSRC D8,SIZE=L,WORK=YES    GET ADDRESS OF 5TH RELATIVE RECORD
         LTR   R14,R14               CHECK RETURN CODE
         BNZ   GDSRERR               BRANCH IF ERROR
         MVC   CE1FA8(2),=CL2'GS'    RECORD ID
         MVC   CE1FA8+2(1),=XL1'00'  RECORD CODE CHECK
         FINDC D8,GDS=YES            READ DATA SET RECORD
         WAITC FINDERR               BRANCH IF ERROR
           .
           .                         UPDATE THE DATA SET RECORD
           .
         FILEC D8,GDS=YES            WRITE DATA SET RECORD
         WAITC FILEERR               BRANCH IF ERROR
***********************************************************************
* READ, UPDATE, AND WRITE THE THIRD RECORD OF THE SAME DATA SET.      *
* WHEN WORK=NO THE USER MUST PASS THE RELATIVE RECORD NUMBER IN THE   *
* FARW EXTENSION.                                                     *
***********************************************************************
         LA    R14,EBW000            ADDRESS OF DATA SET NAME
         MVC   CE1FX8(4),=F'3'       RELATIVE RECORD NUMBER = 3
         GDSRC D8,SIZE=L,WORK=NO     GET ADDRESS OF 3RD RELATIVE RECORD
         LTR   R14,R14               CHECK RETURN CODE
         BNZ   GDSRERR               BRANCH IF ERROR
         MVC   CE1FA8(2),=CL2'GS'    RECORD ID
         MVC   CE1FA8+2(1),=XL1'00'  RECORD CODE CHECK
         FINHC D8,GDS=YES            READ DATA SET RECORD
         WAITC FINDERR               BRANCH IF ERROR
           .
           .                         UPDATE THE DATA SET RECORD
           .
         FILUC D8,GDS=YES            WRITE DATA SET RECORD
         WAITC FILEERR               BRANCH IF ERROR
***********************************************************************
* "CLOSE" THE GENERAL DATA SET.                                       *
***********************************************************************
         LA    R14,EBW000            ADDRESS OF DATA SET NAME
         XC    CE1FM8(1),CE1FM8      VOLUME SEQUENCE NUMBER
         MVC   EBW016(4),=F'0'       RELATIVE RECORD NUMBER
         GDSNC D8,C,RCT=A,SIZE=L,WORK=YES  CLOSE DATA SET
         LTR   R14,R14               CHECK RETURN CODE
         BNZ   GDSNERR               BRANCH IF ERROR
 

ROUTC Macro

When a TPF System is generated, it has message router support. Therefore, application programs should issue the ROUTC macro (rather than one of the Send macros) to transmit a message to a workstation or another application program. The receiving terminal or application program can be hosted by any CPU in the message routing network.

The application program identifies the recipient by giving the symbolic terminal or application program name in a routing control parameter list, RCPL (RC0PL). When the ROUTC macro is issued, the system determines which CPU in the network hosts the receiving terminal or application program and then forwards the message to that CPU. Upon receipt of the message, the host CPU transmits it to the terminal or activates the application program.

The message router, therefore, gives an operational program the ability to communicate with terminals or application programs without regard for whether this CPU or a remote CPU is the host. See TPF Data Communications Services Reference for more information about the message router.

Send Macros

Send macros should be avoided whenever possible. They should be issued only by system programs. The Send macros are device-specific while Route macros require no knowledge of the receiving device. So, user-supplied programs and, where possible, system programs should use the ROUTC macro. It is also recommended that one control output program per user application be given ROUTC responsibility to minimize impact if future upgrading occurs.

Create Macros

An operational program can create independent entries and assign one of four priorities for initiating the processing of the entry. The Create macros available to the operational programs are:

CREDC
Create a deferred entry

CREMC
Create an immediate entry

CRETC
Create time initiated entry

CREXC
Create a low-priority deferred Entry

CREEC
Create an immediate entry with a core block

CRESC
Create a synchronous entry

Entries that are created by the CREDC, CREMC, CRETC, CREXC, and CREEC macros are started on the same I-stream as the program that created them.

The CREDC macro should be used to create an entry and defer its processing to a nonpeak period. The operational program has the ability to initialize the created ECB work area with as many as 96 bytes of parameter information. These parameters can be set up at execution time because the address and byte count of the parameter area is specified in scratch registers R14 and R15. The control program buffers the parameters in an available main storage block and adds this block to the deferred processing list (serviced only in a low activity period). When the deferred list is serviced, Operational Program Zero gets an ECB, moves the parameters into the work area, and releases the interim main storage block. At this time an Enter with No Return (ENTNC) macro is executed, transferring control to the program specified by the CREDC macro. It is important to understand that the repeated use of the CREDC macro can cause a depletion of main storage. When there is insufficient storage to buffer the parameters, the control program forces the ECB issuing the CREDC into a WAITC. The macro will be executed when the necessary main storage becomes available.

The CREMC macro is similar to the CREDC macro except that the interim main storage block buffering the parameters is added to the postinterrupt list. Because excessive use of the CREMC can lock out input messages to the system, this macro should be used carefully.

Operational programs that are above 1052 state can create time-initiated entries by executing the CRETC macro. The control program remembers this request and transfers control to the specified program at the correct time. An ECB is assigned to the created entry when the new program is started. A control block can be passed to the created entry using the LEVEL parameter. The CRETC macro differs from the CREMC and CREDC macros in that the CRETC parameter area is limited to one word, which appears as the first word of the work area in the created ECB. The time interval (3 bytes), in minutes or seconds, that indicates the time relative to the present time, must be specified by the operational program. Both the time interval and the action word are dynamic parameters in that they are set up at execution time in scratch registers R14 and R15. The information required by the control program to retrieve the specified program is specified in the macro expansion.

The CREXC macro is similar to the CREDC macro, but it is more specialized in that it requires more main storage blocks to be available before it will execute. It should be used by programs that create many entries. The use of this macro by doing many creates ensures that there is no degradation of the real-time system by a created shortage of main storage blocks.

The CREEC macro is similar to CREDC and CREMC usage and processing with the additional capability of passing a core block to level zero of the created entry control block. The operational program specifies whether a deferred or immediate entry is to be created and follows the processing paths of CREDC and CREMC, respectively.

Use the CRESC macro to create a synchronous entry. The entry is created in the same subsystem and subsystem user as the issuing program. The issuing program can specify a timeout value to indicate how long the program will wait for the created entry to end. When exiting, the created entry will notify the issuing program by posting completion of an event for which the program is waiting. The issuing program can create as many as 50 entries by coding multiple CRESC macros that specify WAIT=NO, followed by a CRESC WAIT=YES call. The program can pass as much as 4 KB of data to each created entry and can specify on which I-stream to start the entry.

Note:
Limit the use of this macro to prevent storage depletion.

Event Facility--EVNTC, POSTC, EVNWC, EVINC, and EVNQC

This facility allows ECB-controlled programs to define in the control program a subsystem-unique named event, which can be waited on and posted by all ECBs that know its name and data base ID (DBI). This name can be any 8-character, EBCDIC value. Events coded by IBM (*) start with either "SYS" or "I".

The current design allows for three types of trigger mechanisms:

  1. A count of POSTs that have to be done against the named EVENT before it is satisfied.
  2. A 16-bit mask that triggers the event when the mask is reduced to zero by having the event's bits ANDed off by the POST mechanism.
  3. A by-product of the count mechanism that allows the ECB to pass a core block to a second ECB.

The application program creates a named event by issuing the EVNTC macro. The control program assigns an entry in the internal event table and formats it with the information provided by the user. The ECB determines whether a named internal event exists by issuing the EVNQC macro. If the event is not found, processing branches to a path indicated for events not outstanding. When the ECB is ready to wait, it issues the EVNWC macro. To post the named event, an ECB calls the POSTC post event macro. When it is called, the control program searches the internal event table for an event entry with the same name. If no match is found, a nonzero condition code is set and return is made to the application. If a match is found, the type of POSTC is compared against the event type, and if it is not equal, a system error results and the ECB is exited. If the type is a count, the count in the event is decremented by one for the POSTC. If the type is a mask, the mask supplied by the POSTC is ANDed against the mask in the event.

For both count and mask events, another supplied mask is ORed into the return field for the event. If the POSTC macro also specified an error, the error byte is set into the event block and the event is considered triggered even though the mask or count is nonzero.

If the type is core block (CB), the core block reference word (CBRW) from the specified level is copied into the event block and considered to be triggered. A return is made to the posting task with a zero return code.

If the event was triggered and an EVNWC macro has been issued for the event, the event block is placed on the ready list with a postinterrupt address to cause entry into the event completion routine. The event completion routine moves the mask fields back into the event area specified by the EVNWC macro, and it moves the error indicator into the SUD field for the level or event area if level was not specified. The I/O counter is decremented and, if zero, the application program is activated.

On EXITC, any events created by the exiting ECB are destroyed unless another ECB is already waiting for the event, in which case ownership is transferred to the waiting ECB.

As part of the EVNTC macro, a TIMEOUT value can be specified. If the system is above 1052 state, the event will be timed from the time of the first EVNWC until either the event is triggered or the specified time period passes. If the time period passes first, the event is posted complete with error.

After an event has been defined by the EVNTC macro, the EVINC macro can be used to increment dynamically the count for a count-type event. Note, however, that an EVNWC macro cannot have already been issued for the event.

Resource Sharing Facility--ENQC and DEQC

This facility allows multiple ECBs to share a named resource and to serialize access to the resource. To use this facility, a common name has to be agreed on by the programs using it. This name can be any 8-character value. For IBM-written programs, if the name is in EBCDIC, the first 3 characters should be SYS.

To update a shared resource, an ECB issues the ENQC macro with the name of the resource as the parameter. If it is not already in the control program's table, the name is added and the ECB is marked as holding a resource. If the name is in the control program's table, the ECB is queued on the resource entry and a Wait macro is initiated until the resource is freed by the holding ECB. When the holding ECB completes its processing on the shared resource, it issues a DEQC macro for the resource. This frees the resource and allows the control program to transfer ownership to the waiting ECB. If there are no waiting ECBs, the resource entry is cleared.

Alternate Resource Sharing Facility--CORHC and CORUC

This facility is similar to ENQC and DEQC usage and processing. The differences are:

These macros are supplied to provide compatibility for existing applications.

Wait, Exit, Delay Macros

User programs use a Find a File macro (FINDC) to retrieve data stored on the files. However, the data record can be referred to by the user program upon return from the FINDC macro. A WAITC macro is used to guarantee that the input operation has been completed. Only upon return from the WAITC macro can the user program assume that the data record is now in storage and available. The delay for completion of an I/O operation is often substantial when compared to CPU processing speed. Accordingly, following a WAITC macro call, and during the delay pending I/O completion, control can be transferred to another program (or to the current program) for processing of another entry.

The WAITC macro is normally used to ensure completion of an input operation. On output operations (transmit a message or update a data record) the data record is detached from the entry block during calls to the File, Send, or Route macros. Use of the WAITC macro does not ensure completion and the user program cannot determine when output operations are completed. A special mode of operation is provided for the TOUTC macro where a WAITC macro must be called to ensure completion of the output operations. When message processing has been completed, an EXITC macro is called. This program returns all main storage blocks held by this entry to the available storage pools (including the ECB itself), therefore, in that way ending the life of the entry in the system.

Operational programs can defer processing of a low priority task until the activity in the system is sufficiently low to warrant calling it. The Defer (DEFRC) macro is provided for this purpose. The delay prior to service of such entries can be substantial. Accordingly, no records can be held by an entry calling a DEFRC macro and no time-dependent (that is, terminal) response should follow this macro. If the entry is holding considerable working storage, calling of this macro can adversely affect system throughput. The Delay (DLAYC) macro differs from the Defer macro only in that such entries are added to the CPU input list. This list has a higher priority than the CPU defer list.

Note:
Defer and Delay macros are normally called by file maintenance or exception routines, and are not recommended for general use.

Tape Macros

Real-time and General Tape macros provide the operational program with single file, multivolume tape input and output. In order to fulfill different system requirements, two distinct I/O capabilities are provided. The real-time tapes are intended for logging system changes, system performance, and other dynamic maintenance information in the real-time environment. The general tapes provide the tape writing, reading, and searching capabilities required by utility programs.

All tapes need a symbolic 3-character name. The first 2 characters must be alphabetic, and the third must be alphabetic or numeric. Additionally, the first 2 characters for a general tape name cannot be RT.

Realtime Tape Operations

The real-time tapes are Write only tapes that are available to all entries in the system. All hardware tape functions such as writing labels, checking labels, and detecting end-of-volume conditions are handled by the control program. The operational program is relieved of these responsibilities and can assume that the real-time tapes are always available. Records are written on these tapes in the order in which the control program receives TOUTC and TOURC macros. Each record is identified by the subsystem and time stamped. However, because each tape is also available to other entries in the system, an operational program cannot depend on creating consecutive records.

TOUTC Macro

The TOUTC macro writes a record contained in main storage, on the specified real-time tape. This record must be at least 1 byte and no more than 32K bytes length, and must not be altered until the writing operation is complete. The execution of a WAITC macro ensures the completion of the I/O transfer. The record can be in a permanent storage resident area, a working storage block, or the fixed work area in the ECB. To prevent a condition where the tape output record is modified by another entry prior to the completion of the I/O transfer, it is recommended that the output record be located in a storage area held exclusively by the ECB.

When using a TOUTC macro, an operational programmer must communicate the following information to the control program:

These parameters are passed to the control program through the macro expansion and a specified file address reference word (FARW). The macro expansion identifies the request level and the symbolic tape to be used. The starting location of the record and the byte count are stored in the specified request level in the following format:

Figure 1. File Address Reference Word


Core Block Reference Word

The core block reference word is unused. Therefore, the operational program can use any request level without releasing the main storage block held.

TOURC Macro

The TOURC macro writes a record from main storage to the specified real-time tape. The core block must be held by the entry control block at the specified core block reference word. This main storage block is detached from the entry control block at macro time and the writing proceeds independently. Consequently, the operational program cannot determine the status of the Write operation and the call of a WAITC macro is meaningless. Moreover, the request level used in the TOURC macro is immediately available for more use after return from the macro.

Tape Pseudonames

Real-time tape names (like RTA and RTB) can be given aliases, or tape pseudonames. Tape pseudoname RTM, for example, can be mapped to RTA using an RTMAP definition in CEFZ. Such a mechanism provides a means for mapping many names to just a few tape devices.

Both real-time and general tape names may be used as real-time tape pseudonames. However, it is not recommended to use general tape names as real-time tape pseudonames. This is because some tape macros (TDSPC and TSYNC) can be used for both general tapes and real-time tapes. For these macros, an attempt is first made to resolve the specified tape name (which may be a real-time tape pseudoname) to a real-time tape name. If the tape name is successfully resolved then the real-time tape name is used by the macro service routines; otherwise the tape name is treated as a general tape name. Note that tape macros that are used exclusively by real-time tapes (for example, TOURC or TOUTC) or exclusively by general tapes (for example, TOPNC or TPRDC) do not exhibit this behavior. This can lead to confusion if not properly understood.

For example, suppose the general tape name ABC is mapped to the RTM real-time tape. If the operator mounts a ABC tape and an application issues a TSYNC NAME=ABC macro, expecting to synchronize the ABC tape, the RTM tape will be synchronized instead. This is because the real-time tape pseudoname translation is done first.

Only one level of tape name resolution is performed. For example, if the tape pseudoname RTM is mapped to RTB, and the tape pseudoname RTB is mapped to RTA, then TOURC NAME=RTM will write to the RTB tape, not the RTA tape.

General Tape Operations

This section discusses macros for general tape operations.

Open and Close Macros

A number of active general tapes can be on the system at any time. These tapes are separated into distinct sets or groups, each set exclusively associated with a particular active entry. No entry can use another entry's general tapes concurrently. In addition to the tape reading, writing, and searching capabilities provided, the operational program has the facility to define and adjust the definition of its tape set. The Open a General Tape (TOPNC) and Close a General Tape (TCLSC) macros are used for this purpose. A general tape first becomes available to an operational program through the use of the TOPNC macro. The 3-character symbolic general tape name, specified in the TOPNC macro, is used to identify this tape for all general tape macros. When a TOPNC macro is called, the tape name is added to the tape set for that entry. The control program performs the specified labeling functions and presents the desired tape positioned at the initial data record. The TCLSC macro deactivates the specified tape by deleting its tape name from the entry's tape set. Trailer labeling is performed by the control program when the TCLSC macro addresses an output tape.

The running of utility operational programs and allocation of physical tape units for general tape use are controlled by the system operator who is responsible for mounting the proper tapes and initiating the various job phases in their correct sequence. The operator must know where new input or scratch tapes are needed and when output tapes are complete.

Input/Output Macros

The general tape input/output macros are Read a General Tape Record (TPRDC) and Write a General Tape Record (TWRTC). In addition to the I/O operation, each macro performs the appropriate main storage allocation. During a call of the Read macro, the control program gets a main storage block to read the record into. Reference to this main storage block is placed in the specified main storage block reference word when the input operation is complete. Conversely, after the Write macro is completed, the main storage block containing the record is released to the appropriate storage pool. Accordingly, each request for tape I/O by the general tape macros has an associated request level in the ECB. This request level contains the following information:

File Address Reference Word

Unused

Figure 2. Core Block Reference Word


On return from the TPRDC macro, the status of the Read operation is unknown. Consequently, a call to the WAITC macro ensures completion of the I/O. At Wait Return time, the condition code is used to indicate the success or failure of any completed input operation.

On a TWRTC macro, the writing operation and the main storage block containing the data record are detached from the ECB at macro time. Therefore, the request level used is immediately available for use after the return from a TWRTC macro.

Condition Code Settings

The condition code is used with the branch on condition generated in the WAITC macro expansion. It results in a transfer to an operational error routine when an unusual condition or I/O hardware error is detected. At WAITC return time, the condition code has one of two settings: zero or nonzero.

A setting of zero indicates that all input operations (that is, TPRDC macros) were completed as correct length record reads (CLR). On a CLR, the size of the physical record on tape is equal to the size of the main storage block requested at macro time. In this case, control passes to the instruction following the WAITC macro expansion.

A nonzero setting indicates that an unusual condition or I/O hardware error has been detected during at least one of the completed TPRDC macros. In this case control is transferred to the operational error routine by the branch on condition generated in the WAITC macro expansion.

For each I/O hardware error or unusual condition, the control program records an identification character in the entry control block by request level (CE1SUD). Consequently, the operational program can determine which I/O requests were successful, which were unsuccessful, and the nature of the error, by examining this field in the ECB.

Wrong Length Records

At WAITC return time on wrong length record TPRDC macros, the associated core block reference word will be holding a main storage block with the requested record. The byte count for this request level contains the number of bytes read. For a short-length record (SLR), this count will be less than the normal byte count of the requested main storage block. For long-length records (LLR), the count will equal the normal byte count of the requested main storage block (the record will be truncated). The condition code is nonzero and the request level indicator has one of two settings: Short-Length Record (10) or Long-Length Record (08).

End-of-File Condition

A TPRDC macro, which results in an end-of-file (EOF) condition, is aborted in the following manner. At Wait return time the core block reference word corresponding to the TPRDC macro is not holding a main storage block. The condition code is nonzero, and the end-of-file bit is on (04) in the associated request level indicator (CE1SUD).

A number of TPRDC macros can be issued to the same symbolic tape before a WAITC macro. If the first macro call results in an end-of-file (EOF), the remaining macros are aborted in the same manner as the first. If the last macro call results in an end-of-file (EOF), only the last will be canceled. At Wait Return time, the condition code is nonzero and the associated request level indicators in the system error word reflect the completion status of each macro. Only the successfully completed macros will be holding main storage blocks containing the requested records.

Invalid Format Condition

when a TPRDC macro results in an invalid format condition, the ECB is terminated with a system error dump. The block in error causing the condition is displayed in the dump. This error comes about when a variable formatted block is either corrupted on the tape or does not correspond to its own record descriptors. It can occur too when a tape with variable records is defined as having fixed records.

Tape Hardware Error Condition

A dump is taken when errors occur due to equipment failure. The dump and any associated messages should be examined to determine the cause of the problem.

Assign and Reserve Macros

For single entry utility jobs (that is, those that process from start to finish within the same entry control block), the previously described macros provide an adequate macro library. However, some jobs with extensive running time are segmented into a sequence of short phases. Each phase is a unique entry control block in the system and is initiated by the computer operator upon completion of the previous phase. In such a case it is desirable to have one set of tapes associated with the entire life of the job. An example of such a job might be nightly file maintenance, in which a number of capabilities are desirable:

To eliminate operator tape handling between job phases, the operational programmer can use 2 special purpose macros: Reserve General Tape (TRSVC) macro and Assign General Tape (TASNC) macro. These macros are designed to pass an open set of general tapes from an active entry, which is about to exit, to a future entry.

Between these phases the positioning of the tapes remains unchanged. The TRSVC macro reserves the specified tape in the set of this entry or current job phase for use by a future entry or the next phase. When the next phase of the job is started, the new entry makes the tapes available by using a TASNC macro. The following example can clarify the use of the TRSVC and TASNC macros.

Phase I

Macro Tape Comments
TOPNC
TOPNC
TOPNC
SKC,I
SKB,I
SKA,0
These tapes have been mounted by the operator; they are rewound and entered in the tape set as active tapes.
Tape I/O Processing by Phase I
TCLSC SKB General tape SKB is removed from set, rewound, and unloaded.
Tape I/O Processing by Phase I
TRSVC
TRSVC
EXITC
SKA
SCK
General tapes SKA and SKC are reserved for Phase II; their numbering and positioning remain unchanged.

Phase II

Macro Tape Comments
TASNC
TASNC
SKA
SKC
Tapes SKA and SKC are assigned to the ECBs issuing the TASNC macro. Processing continues on each tape from its position at the time of the last TRSVC macro.
Tape I/O Processing by Phase II
TCLSC
TCLSC
EXITC
SKC
SKA
Output tapes SKA and SKC are closed: trailer-labeled, rewound, and unloaded.

Operator Control of Tape Operations

The following is a method of structuring general tape programs to allow for independence from the hardware tape configuration. The operational programmer provides the operator with a run sheet outlining the symbolic tape configuration for each job. This run sheet identifies each tape by general name and type (input, output, scratch, and label information). Using the run sheet, tape units are assigned and the necessary tapes are mounted for the job. The operator then communicates the tape units assigned and their corresponding general tape names to the control program.

Each tape is recorded as being in a ready status by the control program. When the utility job is started the operational program opens each tape with a TOPNC and general tape name. The control program expects to find a ready tape for each TOPNC issued by the operational program. If no such tape exists, the control program sends a message to the operator requesting the desired tape. Return from the TOPNC macro is delayed until the tape is made ready. Only the operator and the control program are concerned with the tape units in use. Therefore, the operational program, working with symbolic general tape names, is independent of the system's physical tape configuration.

Tape Labeling and Multivolume Operations

General tapes used on the online system can be labeled or nonlabeled tapes. All general and real-time output tapes that are used on the online system have header and trailer labels. The control program performs all labeling and label checking independent of the operational programs. The format of the tape labels is consistent with IBM tape label standards. Header labels are checked on all tapes and are written on all output tapes when the tapes are mounted on the system. Mounting informs the control program that this tape is available for use by initializing the tape status table. Mounting can be performed by the operator in response to a TOPNC macro or in anticipation of a request to open a specific tape. The control program writes trailer labels during end-of-volume processing and on TCLSC macros for output tapes. In addition, trailer labels are checked on input tapes to distinguish between end-of-volume and logical end-of-file.

The transition from volume to volume for all input and output tapes is handled automatically by the control program. The operational programs are not aware of this transition and are dealing with a continuous symbolically addressed logical file.

Unit Record Macros

The unit record macros are used by programs to obtain a record from, or output a record to, a unit record device. The macros can be divided into the following categories:

Resource Allocation

USURC
This macro assigns devices to the requesting ECB for its life in the system if no other ECB is using the device. Bit 7 of the first byte CE1URM of the field in the ECB is set to 1 to indicate that a unit record device is assigned to this ECB. This macro must be called before any of the unit record I/O macros can be called.

EXITC
This macro contains code to check bit 7 of CE1URM in the ECB to determine whether any unit record device is associated with the ECB issuing the EXITC macro; if on, the device assigned to this ECB is returned to the system for use by other programs.

PRLNC
This macro will print a line of data to the printer specified by the user.

A WAITC macro must be called to wait for the completion of the I/O operation. The error branch address in the WAITC macro will be taken if an error is detected by the unit record CSECT during the I/O operation.

RDCDC
This macro causes the next card to be read into the specified storage block from the specified card reader.

To ensure completion of the read operation, a WAITC macro must be called before attempting to use the expected record.

Unit Record Control Macro

URCTC
This macro is mainly used to perform unit record error recovery functions and some system utility functions such as UCS buffer load and FCB load. The application program should not have to use this macro.

System Error Detected by Operational Programs (OP)

The SERRC macro is used by operational programs to signal the detection of errors found during processing. Normally, calling this macro causes an appropriately identified message to be transmitted to the CRAS terminal, and areas relevant to the active entry are dumped. For some application programs, the SYSRA macro is used to call system error. The application programmer can select from a variety of the following options when using this macro:

Control Program (CP) Detected Errors

During any control program macro calls, a variety of exceptional conditions can be detected. These conditions are described in the paragraphs that follow. The options available to the application programmer, as previously described, are also available to the system programmer with respect to the usage of the SERRC macro. The systems programmer has the additional option of tailoring dumps of system storage using the dump override table.

Macro Parameter Errors

These errors consist of programming errors that cannot be tolerated in an operational system and are therefore considered irrecoverable for this entry. The control program issues a system error macro with an exit option, which results in a main storage dump, a message to the system console, and the elimination of this entry from the system. (Entries from a terminal operator will be sent to program CPSA, which sends a response to the terminal and then exits.)

I/O Hardware Errors

These errors are caused by hardware malfunctions and are initially processed by control program error routines. If these corrective processes are unsuccessful and the error persists, the control program calls a system error macro, which results in a main storage dump and a message to the system console. Following the WAITC, a transfer is made to the user-specified operational error routine, where corrective action can be started. Because a dump has already been taken by the control program for I/O hardware errors, the operational program should not duplicate this operation by calling another system error.

I/O-Associated Unusual Conditions

These include end-of-file or wrong length record on tape macros, and ID or RCC check failures on Find and File macros. In these cases, the only action taken by the control program is to identify the condition in the entry control block and to transfer to the WAITC-specified error routine in the operational program. At this time, the error routine can assess the severity of the unusual condition and take corrective action if possible. The System Error (SERRC) macro can be used to take a dump and send a message to the system console.

Operational programs regain control only on I/O hardware errors or I/O-associated unusual conditions. These two classes differ in one important respect: the control program takes a dump and sends a message only on I/O hardware errors. Consequently, the operational program error routine should use only the System Error macro on I/O-associated unusual conditions. To aid the operational programs in handling both hardware errors and unusual conditions, the program identifies the condition in the ECB (CE1SUD) before transferring control to the WAITC-specified error routine. There are 2 exceptional condition identification fields in the ECB. They consist of a series of detail indicators (16 bytes, one for each data level and one for the program level) and a summary or gross indicator (1 byte). All indicators (detail and summary) have the same format:

                  Bit
                 X'80' - I/O Hardware Error (main storage dump taken)
                 X'40' - ID Check Failure (IDF) (on read)
                 X'20' - RCC Check Failure (RCCF) (on read)
                 X'10' - Short length Record (SLR)
                 X'08' - Long Length Record (LLR)
 
                 X'04' - End of File (EOF)
                 X'02' - Invalid File Address
                 X'01' - reserved

Bits 4 and 5 will be set by the tape routines to indicate an End-of-Volume (EOV) condition to the user of the TDCTC macro. This combination will only be set for input tapes. Output tapes will set only the EOF indication (Bit 5).

Bits 0 and 4 are set together to indicate Mod Down (main storage dump has been taken).

A bit equal to 1 indicates the presence of the condition; zero indicates the absence of this condition. Consequently, a zero byte indicates no hardware errors or unusual conditions have occurred.

In cases of IDF, RCCF, SLR, and LLR (bits 1, 2, 3, 4), a main storage block is held on the data level. The user's error routine should check these settings in CE1SUD of the ECB.

Both gross (CE1SUG) and detail (CE1SUD) indicators are set by the control program at WAITC return time. Each detail indicator is associated with a particular request level. When an unusual condition occurs, the detail indicator corresponding to the data level for the macro is set with the appropriate bit configuration (such as EOF and RCCF). In addition, the gross byte is updated to indicate that an unusual condition of a particular type has been detected. A WAITC macro can be issued for multiple I/O requests; accordingly, a number of unusual conditions can be present at WAITC return time. The gross byte is a summary and therefore indicates only that conditions of a given type have occurred. The detail indicators define the status of each I/O macro completed as a result of the WAITC macro. Those macros that have completed without unusual conditions or I/O hardware errors have detail indicators of zero. All detail bytes associated with reference levels that are not pertinent to this WAITC macro are set to zero.

Note:
ID or RCC failures on a Write are considered to be software errors resulting in the entry being sent to Exit, whereas if they result from a Read operation, they are considered to be an unusual condition resulting in transfer to the user's error routine.

The user does not need to clear the summary or detail indicators because they are cleared by the control program on finding another WAITC.

Multiple Database Function (MDBF) Macros

The macros required to support a system generated with the multiple database function (MDBF) provide the facility to access resources in a subsystem (SS) other than the one generated for the user. This cross subsystem access can either be directed from an SS or subsystem user (SSU) to the BSS or from the BSS to an SS or SSU. The resources accessed can be one of the following:


Table 1. MDBF Macros

Macro Name Restriction Description
CEBIC System Change SS or SSU Data Resource ID
CROSC System Cross SS Access Service
LEBIC System Load (and index) ECB Resource ID
UATBC General Request for SSU Attribute Table Reference.
Note:
The system macros are described in TPF System Macros and the general ones are described in this publication.

An example of the use of these macros can be found in the CEBIC macro description in TPF System Macros.