This section contains the following topics:
About Data Manipulation Language (DML)
ACCEPT DB-KEY RELATIVE TO CURRENCY
ACCEPT PROCEDURE CONTROL LOCATION
Disconnecting a Record from a Set
FIND/OBTAIN WITHIN SET USING SORT KEY
CA IDMS data manipulation language (DML) consists of statements that enable you to access the database management system (DBMS) and to request Logical Record Facility (LRF) and DC system services. The DML statements can be grouped into categories by function:
This section describes each DML statement that requests an CA IDMS database access or an online service. The DML statements are presented in two ways to help you understand their function in the CA IDMS environment. The following table presents the DML statements by function (for example, retrieval statements and program management statements). Statements that apply to the online environment only are marked with (o). Statements that apply to DC-BATCH only are marked with (dcb). Statements that apply to DC-BATCH or the online environment only are marked with (o,dcb). Following the table, each DML statement is presented in alphabetical order; function, syntax, syntax rules, examples, and associated error-status codes are described in detail. Run-time currency affected by DML statements that navigate the database is described where appropriate.
The WHERE and ON clauses, which are used with LRF DML statements, are described in detail at the end of this section.
Note: All DML operands are positional.
DML Statements Grouped by Function
|
Function |
DML Statement |
|---|---|
|
Control Statements |
|
|
Retrieval Statements |
|
|
Modification Statements |
|
|
Recovery Functions |
|
|
Accept Statements |
|
|
Logical Record Facility |
|
|
Program Management |
|
|
Storage Management |
|
|
Task Management |
|
|
Time Management |
|
|
Scratch Management |
|
|
Queue Management |
|
|
Terminal Management (Basic Mode) |
|
|
Terminal Management (Line Mode) |
|
|
Terminal Management (Mapping Mode) |
|
|
Utility Functions |
|
The ABEND statement terminates the issuing task abnormally. It also invokes or ignores previously established abend exits and writes a task dump to the log file. After completion of the ABEND function, processing control is returned to the CA IDMS program-control module.
►►─── ABEND CODE abend-code ─┬────────────┬─┬─────────────────────────┬─ . ───►◄
├─ DUMP ─────┤ └─ EXITS ─┬─ INVOKED ◄ ─┬─┘
└─ NODUMP ◄ ─┘ └─ IGNORED ───┘
Specifies a four-character user-defined abend code.
Either the symbolic name of a variable-storage field that contains the abend code or the code itself enclosed in quotation marks.
Note: Because the specified abend code appears in the system log and is displayed at the task's terminal, you should not use CA IDMS system abend codes.
Specifies whether to write a formatted task dump to the log file. The default is NODUMP.
Specifies whether to invoke or ignore abend routines established by SET ABEND EXIT (STAE) requests. The default is INVOKED.
The following example specifies an abend request that terminates the issuing task abnormally and requests CA IDMS to write a task dump to the log file and to ignore any abend exits:
ABEND CODE 'U876' DUMP EXITS IGNORED.
Because control is passed to the CA IDMS program-control module, there is no need for the program to check the ERROR-STATUS field.
The ACCEPT statement retrieves the following task-related information:
►►─── ACCEPT ─┬─ TASK CODE ──┬─ INTO return-location . ───────────────────────►◄
├─ TASK ID ────┤
├─ LTERM ID ───┤
├─ PTERM ID ───┤
├─ SYSVERSION ─┤
├─ USER ID ────┤
├─ SCREENSIZE ─┤
└─ SYSTEM ID ──┘
Retrieves the specified information.
Retrieves the 1 through 8 character code used to invoke the current task.
Retrieves the task identifier assigned by CA IDMS. The task identifier is a unique sequence number stored in a PIC S9(8) COMP SYNC (fullword) field. At system startup, the identifier is set to zero; each time a task is executed, the ID is incremented by one.
Retrieves the 1 through 8 character identifier of the logical terminal associated with the current task. If the current task is not associated with a terminal, a null value of all spaces is returned.
Retrieves the 1 through 8 character identifier of the physical terminal associated with the current task. If the current task is not associated with a terminal, a null value of all spaces is returned.
Retrieves the version of the current CA IDMS system. The version number is an integer in the range 0 through 9999 stored in a PIC S9(4) COMP (halfword) field.
Retrieves the 32-character identifier of the user signed on to the logical terminal associated with the current task. If no user is signed on, a null value of all spaces is returned.
Specifies the 8 character name (nodename) by which the DC/UCF system is known to other nodes in the DC/UCF communications network.
Retrieves the screen dimensions of the physical terminal associated with the current task. The screen size is returned to a field that is divided into two PIC S9(4) COMP (halfword) fields. The first halfword contains the row, the second halfword contains the column. For example, a 24-line by 80-character screen is represented by a value of 24 in the first halfword and 80 in the second halfword. If the current task is not associated with a terminal, a null value of zero is returned.
Specifies the location to which CA IDMS returns the requested task-related information.
The symbolic name of a user-defined field; the picture and usage of this field must be compatible with the picture and usage of the requested data.
The following example illustrates ACCEPT statements that retrieve the ID of the current task and the ID of the user signed on to the logical terminal associated with that task:
ACCEPT TASK ID INTO TASK-ID. ACCEPT USER ID INTO USER-ID.
After completion of the ACCEPT function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
4829 |
An invalid parameter has been passed from the program |
The ACCEPT BIND ADDRESS statement moves the bind address of a record to a specified location in program variable storage. This statement is typically requested by a subprogram that requires the address of a record in order to access it.
The ACCEPT BIND ADDRESS statement updates no currencies and requires no currencies to be set relative to the specified record.
►►─── ACCEPT bind-address FROM record-name BIND . ────────────────────────────►◄
A PIC S9(8) COMP SYNC (fullword) field, containing the location into which the bind address of the specified record will be copied.
Specifies the record whose bind address will be copied into the specified location in variable storage.
The name of a record previously bound by the run unit.
The following statement moves the bind address for an EMPLOYEE record to a location identified as REG1 in the requesting subprogram:
ACCEPT REG1 FROM EMPLOYEE BIND.
After completion of the ACCEPT BIND ADDRESS function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
1508 |
The named record is not in the specified subschema |
The ACCEPT DATABASE STATISTICS statement copies system runtime statistics located in the program's IDMS statistics block to program variable storage. This statement can be issued any number of times during the execution of a run unit. For example, you might request database statistics after storing a variable-length record to determine whether the entire record was stored in one place or if fragments were placed in an overflow area.
The ACCEPT DATABASE STATISTICS statement does not reset any of the statistics fields to zero; resetting of IDMS statistics block fields occurs only upon issuing a FINISH command.
The ACCEPT DATABASE STATISTICS statement is used in both the navigational and the non-navigational environments.
►►─── ACCEPT db-statistics FROM IDMS-STATISTICS . ────────────────────────────► ►─┬───────────────────────────────────┬─ ; ──────────────────────────────────►◄ └─EXTENDED (db-stat-extended)───────┘
The name of a fullword-aligned 100-byte field in program variable storage.
The data copied from IDMS-STATISTICS to db-statistics is formatted as follows:
01 DB-STATISTICS 03 DATE-TODAY PIC X(8). 03 TIME-TODAY PIC X(8). 03 PAGES-READ PIC S9(8) COMP. 03 PAGES-WRITTEN PIC S9(8) COMP. 03 PAGES-REQUESTED PIC S9(8) COMP. 03 CALC-TARGET PIC S9(8) COMP. 03 CALC-OVERFLOW PIC S9(8) COMP. 03 VIA-TARGET PIC S9(8) COMP. 03 VIA-OVERFLOW PIC S9(8) COMP. 03 LINES-REQUESTED PIC S9(8) COMP. 03 RECS-CURRENT PIC S9(8) COMP. 03 CALLS-TO-IDMS PIC S9(8) COMP. 03 FRAGMENTS-STORED PIC S9(8) COMP. 03 RECS-RELOCATED PIC S9(8) COMP. *03 LOCKS-REQUESTED PIC S9(8) COMP. *03 SEL-LOCKS-HELD PIC S9(8) COMP. *03 UPD-LOCKS-HELD PIC S9(8) COMP. *03 RUN-UNIT-ID PIC S9(8) COMP. *03 TASK-ID PIC S9(8) COMP. *03 LOCAL-ID PIC X(8). 03 FILLER PIC X(8). *Applies to the central version only
The LOCAL-ID field consists of the four-byte identifier of the interface in which the run unit originated (for example, BATC, DBDC, or CICS) and a unique identifier (fullword) assigned to the run unit by that interface. For batch and CMS run units, this identifier specifies the internal machine time. For CICS run units, this identifier specifies the CICS transaction number assigned to the run unit.
To display the originating interface identifier and the run-unit identifier for a program, the LOCAL-ID field can be moved to a work field:
01 WORK-LOCAL-ID. 02 WORK-LOCAL-ORIGIN PIC X(4). 02 WORK-LOCAL-NUMBER PIC S9(8) COMP.
Alternatively, the DB-STATISTICS record from the data dictionary can be modified by your DBA to define two subordinate fields for the LOCAL-ID field. The DB-STATISTICS record describes the IDMS statistics block. To use this record, code the following statement in program variable storage:
01 COPY IDMS DB-STATISTICS.
The name of a fullword-aligned 100-byte field in program variable storage The data copied from IDMS-STATISTICS to db-stat-extended is formatted as as follows:
01 DB-STAT-EXTENDED
03 SR8-SPLITS PIC S9(8) COMP.
03 SR8-SPAWNS PIC S9(8) COMP.
03 SR8-STORES PIC S9(8) COMP
03 SR8-ERASES PIC S9(8) COMP.
03 SR7-STORES PIC S9(8) COMP
03 SR7-ERASES PIC S9(8) COMP.
03 BINARY-SEARCHES-TOTAL PIC S9(8) COMP.
03 LEVELS-SEARCHED-TOTAL PIC S9(8) COMP.
03 ORPHANS-ADOPTED PIC S9(8) COMP.
03 LEVELS-SEARCHED-BEST PIC S9(4) COMP.
03 LEVELS-SEARCHED-WORST PIC S9(4) COMP.
03 FILLER PIC X(60).
This record layout can be copied from the data dictionary. Code the following statement in program variable storage:
01 INCLUDE IDMS (DB_STAT_EXTENDED).
Note: For more information about the CA IDMS statistics blocks, see the CA IDMS Database Administration Guide.
The following statements establish currency for the sets in which a new EXPERTISE record will participate as a member, store the EXPERTISE record, and move statistics regarding the stored EXPERTISE record to the DB-STATISTICS location in main storage:
MOVE EMP-ID-IN TO EMP-ID-0415. FIND CALC EMPLOYEE. MOVE SKILL-ID-IN TO SKILL-ID-0455. FIND CALC SKILL. STORE EXPERTISE. ACCEPT DB-STATISTICS FROM IDMS-STATISTICS.
After completion of the ACCEPT DATABASE STATISTICS function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
1518 |
The database statistics location has not been bound properly |
The ACCEPT DB-KEY FROM CURRENCY statement moves the db-key of the current record of run unit, record type, set, or area to a specified location in program variable storage. Records whose db-keys are saved in this manner are available for subsequent direct access by using a FIND/OBTAIN DB-KEY statement.
Note: You must establish currency before using this statement. If no currency has been established, the DBMS returns 0000 to the ERROR-STATUS field and -1 to the db-key field.
ACCEPT DB-KEY FROM CURRENCY does not update any currencies.
►►─ ACCEPT db-key-location FROM ─┬───────────────┬──── CURRENCY ─────────────►
├─ record-name ─┤
├─ set-name ────┤
└─ area-name ───┘
►─┬──────────────────────────────┬─── . ────────────────────────────────────►◄
└ PAGE-INFO page-info-location ┘
A PIC S9(8) COMP SYNC (fullword) field. Identifies the location in variable storage that will contain the db-key of the specified record.
Specifies the record whose db-key will be placed in the specified location. By default, if you omit a record, set, or area qualifier, the db-key of the record that is current of the run unit is saved.
record-name Saves the db-key of the record that is current of the specified record type.
set-name Saves the db-key of the record that is current of the specified set.
area-name Saves the db-key of the record that is current of the specified area.
Indicates that the page-info of the specified record is collected and recorded into page-info-location.
Identifies the location in variable storage that contains the page-info of the requested record. This field is a PIC S9(8) COMP SYNC (fullword) field.
The following statements establish a DEPARTMENT record as current of run unit and save its db-key in location SAVE-DB-KEY:
MOVE '8683' TO DEPT-ID-0410. FIND CALC DEPARTMENT. ACCEPT SAVE-DB-KEY FROM CURRENCY.
Note: The same results can be accomplished using the following COBOL MOVE statement:
MOVE DB-KEY TO SAVE-DB-KEY.
After completion of the ACCEPT DB-KEY FROM CURRENCY function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
1503 |
The dbkey that is the object of an ACCEPT has been invalidated. This can only occur when a run unit is sharing a transaction with other database sessions. The 03 minor status is returned if the run unit tries to retrieve a dbkey and a currency has been invalidated because of changes made by another database session that is sharing the same transaction. |
|
1508 |
The named record or set is not in the subschema. The program has probably invoked the wrong subschema. |
|
1523 |
The named area is not in the subschema. |
The ACCEPT DB-KEY RELATIVE TO CURRENCY statement moves a selected db-key to a specified location in program variable storage. The db-key moved to variable storage can be the db-key of the next, prior, or owner record relative to the current record of set.
This version of the ACCEPT statement allows you to save the db-key of a record within a set without actually having to access the record. Records whose db-keys are saved in this manner are available for subsequent direct access by using a FIND/OBTAIN DB-KEY statement.
Note: You must establish currency before using this statement. If no set currency has been established, the DBMS returns 0000 to the ERROR-STATUS field and -1 to the db-key-location field.
Currency
ACCEPT DB-KEY RELATIVE TO CURRENCY does not update any currencies.
►►─── ACCEPT db-key-location FROM set-name ─┬─ NEXT ──┬─ CURRENCY ───────────►
├─ PRIOR ─┤
└─ OWNER ─┘
►─┬──────────────────────────────┬─── . ────────────────────────────────────►◄
└ PAGE-INFO page-info-location ┘
A PIC S9(8) COMP SYNC (fullword) field. Identifies the location in variable storage that will contain the db-key of the requested record.
Identifies the record whose db-key will be moved into the specified location.
set-name The name of a set included in the subschema. Native VSAM users:. NEXT/PRIOR/OWNER CURRENCY cannot be requested for sets defined for native VSAM records.
Saves the db-key of the next record relative to the record that is current of the specified set. NEXT CURRENCY cannot be requested unless the specified set has prior pointers; prior pointers ensure that the next pointer in the prefix of the current record does not point to a logically deleted record.
Saves the db-key of the prior record relative to the record that is current of the specified set. PRIOR CURRENCY cannot be requested unless the specified set has prior pointers.
Note: No indication of an end-of-set condition is possible for an ACCEPT NEXT or PRIOR. A retrieval command must be issued to determine whether the next or prior record in the set occurrence is the owner record.
Saves the db-key of the owner of the record that is current of the specified set. A request for OWNER CURRENCY cannot be executed unless the specified set has owner pointers. However, if the current record of the named set is the owner record occurrence, requests for OWNER CURRENCY return the db-key of the record itself, even if this set does not have owner pointers.
Note: When a record declared as an optional or manual member of a set is accessed, it is not established as current of set if it is not currently connected to an occurrence of the specified set. A subsequent attempt to access the owner record will locate instead the owner of the current record of set. In such cases, determine whether the retrieved record is actually a set member before executing the ACCEPT DB-KEY FROM OWNER CURRENCY statement. The IF statement, explained later in this chapter, can be used for this purpose.
Indicates that the page-info of the specified record is collected and recorded into page-info-location.
Identifies the location in variable storage that contains the page-info of the requested record. This field is a PIC S9(8) COMP SYNC (fullword) field.
The following statements access the EMP-EXPERTISE set and save the db-key of the owner record of the SKILL-EXPERTISE set:
MOVE '0119' TO EMP-ID-0415. FIND CALC EMPLOYEE. FIND FIRST WITHIN EMP-EXPERTISE. ACCEPT SAVE-DB-KEY FROM SKILL-EXPERTISE OWNER CURRENCY.
After completion of the ACCEPT DB-KEY RELATIVE TO CURRENCY function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
1503 |
The dbkey that is the object of an ACCEPT has been invalidated. This can only occur when a run unit is sharing a transaction with other database sessions. The 03 minor status is returned if the run unit tries to retrieve a dbkey and a currency has been invalidated because of changes made by another database session that is sharing the same transaction. |
|
1508 |
The named set is not in the subschema. The program has probably invoked the wrong subschema. |
The ACCEPT page-info-location statement moves the page information for a given record to a specified location in program variable storage. Page information that is saved in this manner is available for subsequent direct access by using a FIND/OBTAIN DB-KEY statement.
The dbkey radix portion of the page information can be used in interpreting a dbkey for display purposes and in formatting a dbkey from page and line numbers. The dbkey radix represents the number of bits within a dbkey value that are reserved for the line number of a record. By default, this value is 8, meaning that up to 255 records can be stored on a single page of the area. Given a dbkey, you can separate its associated page number by dividing the dbkey by 2 raised to the power of the dbkey radix. For example, if the dbkey radix is 4, you would divide the dbkey value by 2**4. The resulting value is the page number of the dbkey. To separate the line number, you would multiply the page number by 2 raised to the power of the dbkey radix and subtract this value from the dbkey value. The result would be the line number of the dbkey. The following two formulas can be used to calculate the page and line numbers from a dbkey value:
►►─── ACCEPT page-info-location FOR record-name . ────────────────────►◄
Retrieves the specified information.
page-info-location Specifies a four-byte field that may be defined either as a group field or as a fullword field (PIC S9(8) COMP). Identifies the location in variable storage that contains page information for the specified record. Upon successful completion of this statement, the first two bytes of the field contain the page group number and the last two bytes contain a value that may be used for interpreting dbkeys.
Specifies the record whose page information will be placed in the specified location.
Specifies the record whose page information will be placed in the specified location.
The following example retrieves the page information for the DEPARTMENT record and uses the dbkey format information to transform a page number into a dbkey.
01 W-PG-INFO. 02 W-GRP-NUM PIC S9(4) COMP. 02 W-DBK-FORMAT PIC 9(4) COMP. ACCEPT W_PG_INFO FOR DEPARTMENT. MOVE W-PAGE TO W-DBKEY. PERFORM ADJUST-PAGE W-DBK-FORMAT TIMES. ADJUST-PAGE SECTION. MULTIPLY W-DBKEY BY 2.}
After completion of the ACCEPT page-info-location function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
1508 |
The named record is not in the subschema. The program probably invoked the wrong subschema. |
The ACCEPT PROCEDURE CONTROL LOCATION statement copies the 256-byte application program information block associated with a previously defined database procedure to a specified location in program variable storage. A BIND PROCEDURE statement (explained later in this chapter) previously placed information into this block; this information may have been subsequently updated by the procedure.
The ACCEPT PROCEDURE CONTROL LOCATION statement should be used only by programs running under, but in a different partition from, the central version.
►►─── ACCEPT procedure-control-location FROM procedure-name PROCEDURE . ──────►◄
The fullword-aligned 256-byte location in variable storage to which the application program information block is to be copied.
The name of the database procedure whose application program information block is to be copied into variable storage. Procedure-name must refer to an eight-character field in variable storage.
The following statement copies the application program information block used by the CHECKALL procedure to the location identified as CHECK-IT in main storage:
ACCEPT CHECK-IT FROM CHECKALL PROCEDURE.
After completion of the ACCEPT PROCEDURE CONTROL LOCATION function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
1508 |
The named procedure is not in the specified subschema |
|
1518 |
The procedure control location has not been bound properly |
The ACCEPT TRANSACTION STATISTICS statement copies the contents of the transaction statistics block (TSB) to a location in program variable storage. Optionally, the statement can also write the TSB to the DC system log file and you can define the length of the TSB.
►►─── ACCEPT TRANSACTION STATISTICS ──┬───────────┬────────────────────────────►
├─ WRITE ◄ ─┤
└─ NOWRITE ─┘
►───┬──────────────────────────────────┬──────────────────────────────────────►
└─ INTO return-stat-data-location ─┘
►───┬─────────────────────────────────┬────────────────────────────────────;──►◄
└─ LENGTH ─┬─ 388 ◄───────────┬───┘
└─ len-return-TSB ─┘
Specifies whether the TSB is written to the DC system log file.
Default: WRITE
Specifies the WORKING-STORAGE SECTION or LINKAGE SECTION data area into which to return the TSB.
A fullword-aligned 388-byte field (you can customize the length using the LENGTH parameter).
The data copied from the TSB to return-stat-data-location is formatted as follows:
01 STATISTICS-BLOCK. 03 SYS-INTERN1 PIC X(8) SYSTEM INTERNAL USE ONLY 03 PROG-CALL PIC S9(8) COMP # OF PROGRAMS CALLED 03 PROG-LOAD PIC S9(8) COMP # OF PROGRAMS LOADED 03 TERM-READ PIC S9(8) COMP # OF TERMINAL READS 03 TERM-WRITE PIC S9(8) COMP # OF TERMINAL WRITES 03 TERM-ERROR PIC S9(8) COMP # OF TERMINAL ERRORS 03 STORAGE-GET PIC S9(8) COMP # OF STORAGE GETS 03 SCRATCH-GET PIC S9(8) COMP # OF SCRATCH GETS 03 SCRATCH-PUT PIC S9(8) COMP # OF SCRATCH PUTS 03 SCRATCH-DEL PIC S9(8) COMP # OF SCRATCH DELETES 03 QUEUE-GET PIC S9(8) COMP # OF QUEUE GETS 03 QUEUE-PUT PIC S9(8) COMP # OF QUEUE PUTS 03 QUEUE-DEL PIC S9(8) COMP # OF QUEUE DELETES 03 GET-TIME PIC S9(8) COMP # OF GET TIMES 03 SET-TIME PIC S9(8) COMP # OF SET TIMES 03 DB-SRVREQ PIC S9(8) COMP # OF DB SERVICE REQUESTS 03 MAX-STACK PIC S9(8) COMP MAX WORDS USED IN STACK 03 USER-TIME PIC S9(8) COMP USER MODE TIME (10**-4 SEC) 03 SYS-TIME PIC S9(8) COMP SYS MODE TIME (10**-4 SEC) 03 WAIT-TIME PIC S9(8) COMP WAIT TIME (10** -4 SEC) 03 MAX-RCE-USED PIC S9(8) COMP MAXIMUM NUMBER OF RCES USED 03 MAX-RLE-USED PIC S9(8) COMP MAXIMUM NUMBER OF RLES USED 03 MAX-DPE-USED PIC S9(8) COMP MAXIMUM NUMBER OF DPES USED 03 STG-HI-MARK PIC S9(8) COMP STORAGE HIGH WATER MARK 03 FREESTG-REQ PIC S9(8) COMP # OF FREE STORAGE REQUESTS 03 SYS-SERV PIC S9(8) COMP # OF SYSTEM SERVICE REQUEST 03 SYS-INTERN2 PIC X(8) SYSTEM INTERNAL USE ONLY 03 PAGES-READ PIC S9(8) COMP # OF PAGES READ 03 PAGES-WRIT PIC S9(8) COMP # OF PAGES WRITTEN 03 PAGES-REQ PIC S9(8) COMP # OF PAGES REQUESTED 03 CALC-NO PIC S9(8) COMP # OF CALC RECS NO OFLOW 03 CALC-OF PIC S9(8) COMP # OF CALC RECS OFLOW 03 VIA-NO PIC S9(8) COMP # OF VIA RECS NO OFLOW 03 VIA-OF PIC S9(8) COMP # OF VIA RECS OFLOW 03 RECS-REQ PIC S9(8) COMP # OF RECS REQUESTED 03 RECS-CURR PIC S9(8) COMP # OF RECS CURR OF RU 03 DB-CALLS PIC S9(8) COMP # OF DBMS CALLS 03 FRAG-STORED PIC S9(8) COMP # OF FRAGMENTS STORED 03 RECS-RELO PIC S9(8) COMP # OF RECS RELOCATED 03 TOT-LOCKS PIC S9(8) COMP TOTAL # OF LOCKS ACQUIRED 03 SHR-LOCKS PIC S9(8) COMP # OF SHARE LOCKS HELD 03 NSH-LOCKS PIC S9(8) COMP # OF NON-SHARE LOCKS HELD 03 LOCKS-FREED PIC S9(8) COMP # OF LOCKS FREED 03 SR8-SPLITS PIC S9(8) COMP # OF SR8 SPLITS 03 SR8-SPAWN PIC S9(8) COMP # OF SR8 SPAWNS 03 SR8-STORE PIC S9(8) COMP # OF SR8S STORED 03 SR8-ERASE PIC S9(8) COMP # OF SR8S ERASED 03 SR7-STORE PIC S9(8) COMP # OF SR7S STORED 03 SR7-ERASE PIC S9(8) COMP # OF SR7S ERASED 03 BTREE-SRCH PIC S9(8) COMP # OF BTREE SEARCHES 03 BTREE-LEVEL PIC S9(8) COMP # OF BTREE LEVELS SEARCHED 03 ORPHANS PIC S9(8) COMP # OF ORPHANS ADAPTED 03 BTREE-LEV-B PIC S9(4) COMP # OF LVLS SRCH'D (BEST CASE) 03 BTREE-LEV-W PIC S9(4) COMP # OF LVLS SRCH'D (WORST CASE) 03 RECS-UPD PIC S9(8) COMP # OF RECS UPDATED 03 PAGE-INCACHE PIC S9(8) COMP # OF PAGES FOUND IN CACHE 03 PAGE-INPREFET PIC S9(8) COMP # OF PAGES FOUND IN PREFETCH 03 RESERVED PIC X(8) RESERVED FOR FUTURE USE 03 SYS-INTERN3 PIC X(8) SYSTEM INTERNAL USE ONLY 03 USER-ID PIC X(32) DC USER ID 03 LTERM-ID PIC X(8) LOGICAL TERMINAL ID 03 USER-SUPP-ID PIC X(8) USER-SUPPLIED ID 03 BIND-DATE PIC S9(7) COMP-3 DATE BIND COMMAND ISSUED 03 BIND-TIME PIC S9(8) COMP TIME BIND COMMAND ISSUED 03 TRANSTAT-FLGS PIC S9(8) COMP FOUR 1-BYTE FLAGS 03 SYS-INTERN4 PIC X(8) SYSTEM INTERNAL USE ONLY 03 SQL-COMMANDS PIC S9(8) COMP # OF SQL COMMANDS EXECUTED 03 SQL-FETCH PIC S9(8) COMP # OF ROWS FETCHED 03 SQL-INSERT PIC S9(8) COMP # OF ROWS INSERTED 03 SQL-UPDATE PIC S9(8) COMP # OF ROWS UPDATED 03 SQL-DELETE PIC S9(8) COMP # OF ROWS DELETED 03 SQL-SORTS PIC S9(8) COMP # OF SORTS PERFORMED 03 SQL-ROWSORT PIC S9(8) COMP # OF ROWS SORTED 03 SQL-MINRSORT PIC S9(8) COMP MINIMUM ROWS SORTED 03 SQL-MAXRSORT PIC S9(8) COMP MAXIMUM ROWS SORTED 03 SQL-AMCMPL PIC S9(8) COMP # OF AM RECOMPILES 03 SQL-RESERVED PIC X(32) RESERVED FOR FUTURE USE
If you extend the length to 560 bytes, the full TRANSACTION-STATISTICS are also included. The following block can be expanded using the COPY IDMS TRANSACTION-STATISTICS statement:
01 TRANSACTION-STATISTICS.
03 TSB-STATS-R18 PIC X(560).
03 TSB-STATS-R17 REDEFINES TSB-STATS-R18.
04 TSB-DC-STATS PIC X(108).
04 TSB-DC-STATS1 REDEFINES TSB-DC-STATS.
05 SYS-INTERN1 PIC X(8).
05 PROG-CALL PIC S9(8) COMP.
05 PROG-LOAD PIC S9(8) COMP.
05 TERM-READ PIC S9(8) COMP.
05 TERM-WRITE PIC S9(8) COMP.
05 TERM-ERROR PIC S9(8) COMP.
05 STORAGE-GET PIC S9(8) COMP.
05 SCRATCH-GET PIC S9(8) COMP.
05 SCRATCH-PUT PIC S9(8) COMP.
05 SCRATCH-DEL PIC S9(8) COMP.
05 QUEUE-GET PIC S9(8) COMP.
05 QUEUE-PUT PIC S9(8) COMP.
05 QUEUE-DEL PIC S9(8) COMP.
05 GET-TIME PIC S9(8) COMP.
05 SET-TIME PIC S9(8) COMP.
05 DB-SRVREQ PIC S9(8) COMP.
05 MAX-STACK PIC S9(8) COMP.
05 USER-TIME PIC S9(8) COMP.
05 SYS-TIME PIC S9(8) COMP.
05 WAIT-TIME PIC S9(8) COMP.
05 MAX-RCE-USED PIC S9(8) COMP.
05 MAX-RLE-USED PIC S9(8) COMP.
05 MAX-DPE-USED PIC S9(8) COMP.
05 STG-HI-MARK PIC S9(8) COMP.
05 FREESTG-REQ PIC S9(8) COMP.
05 SYS-SERV PIC S9(8) COMP.
04 TSB-DB-STATS PIC X(72).
04 TSB-DB-STATS1 REDEFINES TSB-DB-STATS.
05 SYS-INTERN2 PIC X(8).
05 PAGES-READ PIC S9(8) COMP.
05 PAGES-WRIT PIC S9(8) COMP.
05 PAGES-REQ PIC S9(8) COMP.
05 CALC-NO PIC S9(8) COMP.
05 CALC-OF PIC S9(8) COMP.
05 VIA-NO PIC S9(8) COMP.
05 VIA-OF PIC S9(8) COMP.
05 RECS-REQ PIC S9(8) COMP.
05 RECS-CURR PIC S9(8) COMP.
05 DB-CALLS PIC S9(8) COMP.
05 FRAG-STORED PIC S9(8) COMP.
05 RECS-RELO PIC S9(8) COMP.
05 TOT-LOCKS PIC S9(8) COMP.
05 SHR-LOCKS PIC S9(8) COMP.
05 NSH-LOCKS PIC S9(8) COMP.
05 LOCKS-FREED PIC S9(8) COMP.
04 TSB-IX-STATS PIC X(40).
04 TSB-IX-STATS1 REDEFINES TSB-IX-STATS.
05 SR8-SPLITS PIC S9(8) COMP.
05 SR8-SPAWN PIC S9(8) COMP.
05 SR8-STORE PIC S9(8) COMP.
05 SR8-ERASE PIC S9(8) COMP.
05 SR7-STORE PIC S9(8) COMP.
05 SR7-ERASE PIC S9(8) COMP.
05 BTREE-SRCH PIC S9(8) COMP.
05 BTREE-LEVEL PIC S9(8) COMP.
05 ORPHANS PIC S9(8) COMP.
05 BTREE-LEV-B PIC S9(4) COMP.
05 BTREE-LEV-W PIC S9(4) COMP.
04 TSB-DB-STATS-EXTENDED PIC X(20).
04 TSB-DB-STATS-EXTENDED1
REDEFINES TSB-DB-STATS-EXTENDED.
05 RECS-UPD PIC S9(8) COMP.
05 PAGE-INCACHE PIC S9(8) COMP.
05 PAGE-INPREFET PIC S9(8) COMP.
05 RESERVED PIC X(8).
04 TSB-HDR PIC X(68).
04 TSB-HDR1 REDEFINES TSB-HDR.
05 SYS-INTERN3 PIC X(8).
05 USER-ID PIC X(32).
05 LTERM-ID PIC X(8).
05 USER-SUPP-ID PIC X(8).
05 BIND-DATE PIC S9(7) COMP-3.
05 BIND-TIME PIC S9(8) COMP.
05 TRANSTAT-FLGS PIC S9(8) COMP.
04 TSB-SQL-STATS PIC X(80).
04 TSB-SQL-STATS1 REDEFINES TSB-SQL-STATS.
05 SYS-INTERN4 PIC X(8).
05 SQL-COMMANDS PIC S9(8) COMP.
05 SQL-FETCH PIC S9(8) COMP.
05 SQL-INSERT PIC S9(8) COMP.
05 SQL-UPDATE PIC S9(8) COMP.
05 SQL-DELETE PIC S9(8) COMP.
05 SQL-SORTS PIC S9(8) COMP.
05 SQL-ROWSORT PIC S9(8) COMP.
05 SQL-MINRSORT PIC S9(8) COMP.
05 SQL-MAXRSORT PIC S9(8) COMP.
05 SQL-AMCMPL PIC S9(8) COMP.
05 SQL-RESERVED PIC X(32).
04 TSB-STATS-DCX PIC X(168).
04 TSB-STATS-DCX1 REDEFINES TSB-STATS-DCX.
05 TSB-STATS-DCX-FILLER PIC X(8).
05 TSB-SYS-MODE-CPU-TOD PIC 9(18) COMP.
05 TSB-SYS-ZIIP-ON-CP-TOD
PIC 9(18) COMP.
05 TSB-SYS-ZIIP-ON-ZIIP-TOD
PIC 9(18) COMP.
05 TSB-USER-MODE-CPU-TOD
PIC 9(18) COMP.
05 TSB-TCB-CPU-TIME-TOD PIC 9(18) COMP.
05 TSB-SRB-CPU-TIME-TOD PIC 9(18) COMP.
05 TSB-STATS-DCX-FILL01 PIC X(112).
Specifies the length of the returned TSB. To retrieve all statistics including the DC extended statistics section that records CPU times in the Time of Day (TOD) format, specify LENGTH as 560.
Specifies either the symbolic name of a user-defined field that contains the length of the TSB, or the length expressed as a numeric constant.
Limits: Integer of 388 or greater
Default: If you do not specify len-return-TSB, the first 388 bytes of the TSB are returned.
The following statement returns the contents of the TSB to STATISTICS-BLOCK and writes transaction statistics to the log file:
ACCEPT TRANSACTION STATISTICS WRITE INTO STATISTICS-BLOCK.
After completion of the ACCEPT TRANSACTION STATISTICS function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
3801 |
Storage for the transaction statistics block is not available; to wait would cause a deadlock |
|
3813 |
No transaction statistics block exists; a BIND TRANSACTION STATISTICS request has not been issued |
|
3831 |
Either the parameter list is invalid or no logical terminal element (LTE) is associated with the issuing task |
|
3850 |
The collection of transaction statistics or task statistics has not been enabled during system generation |
The ATTACH statement initiates a new task by acquiring the necessary control blocks and storage and by adding the task to its dispatching list. CA IDMS initializes the attached task and queues it up for execution; the issuing program receives control in accordance with normal dispatching priority.
►►─── ATTACH TASK CODE 'task-code' ─┬─────────────────────┬─┬──────────┬─ . ──►◄
└─ PRIORITY priority ─┘ ├─ WAIT ◄ ─┤
└─ NOWAIT ─┘
Either the symbolic name of a user-defined field that contains the task code or the code itself enclosed in quotation marks.
The referenced task code must have been defined during system generation or dynamically by using the DCMT VARY DYNAMIC TASK command.
Specifies the dispatching priority of the attached task.
priority Either the symbolic name of a user-defined field that contains the dispatching priority or the priority itself expressed as a numeric constant in the range 000 through 240. By default, if you do not specify a priority or its location, the priority established during system generation for the specified task code, terminal, and user is used.
Specifies that the issuing task waits until the maximum task condition no longer exists and the specified task can be attached.
This is the default.
Specifies that the issuing task does not wait for the task to be attached. When NOWAIT is specified, the program should check the ERROR-STATUS field in the CA IDMS communications block to determine if the ATTACH request has been completed. If the ERROR-STATUS value is 3711, indicating that a maximum task condition exists, the request has not been serviced and the program should perform alternative processing before reissuing the ATTACH request.
The following example illustrates how to initiate task TASKATCH and assign it a dispatching priority of 199:
ATTACH TASK CODE 'TASKATCH' PRIORITY 199 NOWAIT.
After completion of the ATTACH function, the ERROR-STATUS field of the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
3711 |
The task cannot be attached because the maximum number of tasks has already been attached. |
|
3712 |
The specified task code is not known to the CA IDMS system. |
|
3758 |
The task cannot be attached because the maximum number of concurrent tasks threads was exceeded. |
|
3799 |
The requested task could not be attached because the current user is not authorized to execute the task. |
The BIND MAP statement identifies the location of a map request block (MRB) and initializes MRB fields. For each MRB used by a program, code a BIND MAP statement; for each record defined to a map, code a BIND MAP RECORD statement.
BIND MAP statements can be global or record-specific, as follows:
Typically, a program issues a global BIND MAP statement for each map, followed by BIND MAP statements for each map record used by the program.
You can request the precompiler to include global and record-specific BIND MAP statements automatically by using a COPY IDMS MAP-BINDS statement (see Chapter 5:). COPY IDMS MAP-BINDS includes the necessary BINDS for all maps and map records defined for the program.
The program can alter the storage address for a map record at any time by issuing another BIND MAP statement for that record. After the initial global bind (BIND MAP), all map records are considered unbound; map operations that use those records will have no effect on storage. After binding a map record to a storage address (BIND MAP RECORD), subsequent map operations will use that address to access the record. To unbind a map record, issue a record-specific BIND MAP statement that specifies the TO NULL option.
┌────────────────────────────────────────────────────────────────────────┐
►►─▼─ BIND MAP map-name ─┬─────────────────────────────────────────────┬─ . ┴─►◄
└─ RECORD rec-name ─┬────────────────────────┬┘
└─ TO ─┬─ NULL ─────────┬┘
└─ rec-location ─┘
The name of an existing map. The map version defaults to the version specified for the map in the program's MAP SECTION.
Initializes the variable storage address of the named record in the MRB.
The name of a record used by the map.
Specifies whether the record is to be unbound or bound to a specified address.
Leaves the record unbound.
The symbolic name of a user-defined field that contains the address to which the record is to be bound. Record-location defaults to record-name. Subsequent I/O operations will use this area of storage for any operation associated with the record.
The following statements bind the map EMPMAPLR and its five associated map records:
BIND MAP EMPMAPLR. BIND MAP EMPMAPLR RECORD EMPLOYEE. BIND MAP EMPMAPLR RECORD DEPARTMENT. BIND MAP EMPMAPLR RECORD JOB. BIND MAP EMPMAPLR RECORD OFFICE. BIND MAP EMPMAPLR RECORD EMP-DATE-WORK-REC.
After completion of the BIND MAP function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
The BIND PROCEDURE statement establishes communication between a program and a DBA-written database procedure (for example, a security routine). You should use this statement only when the application program is required to pass to the procedure more information than is provided by the DBMS itself. Such instances are unusual; in most cases, you will not be aware of which procedures gain control before or after various DML functions.
The BIND PROCEDURE statement is used in both the navigational and the non-navigational environments.
►►─── BIND PROCEDURE FOR procedure-name TO procedure-control-location . ──────►◄
Specifies the database procedure in program variable storage to be made available to the program.
Specifies the 256-byte (fixed-length) location to which the named procedure will be bound.
A program that runs in a different partition from the central version may need to pass certain information to the database procedure. When the DBMS invokes the database procedure, this information is copied from the program storage area identified by procedure-control-location into the IDMS application program information block. The information passed is the information in procedure-control-location when the BIND PROCEDURE was performed; it is not the information in the program's storage at the time of the procedure call.
The following statement binds the procedure with the variable name PROGCHEK to the 256-byte area PROC-CTL:
BIND PROCEDURE FOR PROGCHEK TO PROC-CTL.
After completion of the BIND PROCEDURE function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
1400 |
The BIND PROCEDURE statement cannot be recognized. This code usually indicates that the IDMS communications block (SUBSCHEMA-CTRL) is not aligned on a fullword boundary. |
|
1408 |
The named procedure is not in the specified subschema. |
|
1418 |
The procedure has been bound improperly to location 0. |
|
1472 |
The available memory is insufficient to dynamically load the database procedure. |
|
1474 |
An attempt to load a module from the load/core-image library or DDLDCLOD has failed. |
The BIND RECORD statement establishes addressability for a record in program variable storage. In most cases, you need not issue individual BIND RECORD statements since the necessary statements are generated as a group by the COPY IDMS SUBSCHEMA-BINDS statement (see Chapter 5:). However, you can issue BIND RECORD commands separately as necessary (for example, to bind several records to the same storage location). In any case, addressability must be established for each subschema record to be used by the program.
The program should perform the IDMS-STATUS routine after each BIND RECORD statement to ensure that the statement was executed successfully. When AUTOSTATUS is in use (see AUTOSTATUS Protocols), a PERFORM IDMS-STATUS operation occurs automatically after each BIND RECORD statement, even if the BIND RECORD statements are generated as a group by a COPY IDMS SUBSCHEMA-BINDS statement. You should use COPY IDMS SUBSCHEMA-BINDS only when AUTOSTATUS is in use.
►►─── BIND ─┬─ record-name ─┬──────────────────────┬─┬─ . ────────────────────►◄
│ └─ TO record-location ─┘ │
│ │
└─ record-location WITH record-name ─────┘
Specifies the record to be bound to a location in variable storage.
The specified record must be included in the subschema.
Specifies the location to which the record is to be bound. The location corresponds to the record description as copied into the program manually or automatically through DATA DIVISION statements.
Note: record-location must be the same length as record-name.
Note: Exercise caution when using the TO record-location option because source-object mismapping can result from improper use. In cases where more than one copy of a given database record description is present in the program, you must ensure that the proper record description is bound at the proper time.
Binds a record name literal, specified by record-name, with a variable storage record description, specified by record-location. Record-name must specify a record included in the subschema.
The following statement binds the EMPLOYEE record:
BIND EMPLOYEE.
After completion of the BIND RECORD function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
1400 |
The BIND RECORD statement cannot be recognized. This code usually indicates that the IDMS communications block (SUBSCHEMA-CTRL) is not aligned on a fullword boundary. |
|
1408 |
The named record is not in the subschema. The program has probably invoked the wrong subschema. |
|
1418 |
The record has been bound improperly to location 0. |
|
1472 |
The available memory is insufficient to dynamically load a database procedure. |
|
1474 |
An attempt to load a module from the load/core-image library or DDLDCLOD has failed. |
The BIND RUN-UNIT statement establishes a run unit for accessing the database, identifies the location of the IDMS communications block being used, and names the subschema to be loaded for the run unit. BIND RUN-UNIT can also name the node under which the run unit will execute and identify the database to be accessed. BIND RUN-UNIT must be the first functional DML call passed to the DBMS at execution time; it must logically precede all other DML statements (for example, BIND RECORD, READY, FIND) in the program's PROCEDURE DIVISION. UTM modes only: You must move LOW VALUES to SUBSCHEMA-CTRL before issuing the BIND RUN-UNIT statement.
When AUTOSTATUS is in use, COPY IDMS SUBSCHEMA BINDS can be used to automatically invoke the BIND RUN-UNIT statement and the appropriate BIND RECORD statements (see Chapter 5:).
If program registration is in effect (that is, all programs must be registered in the data dictionary before compilation), the program must initialize the PROGRAM-NAME field of the IDMS communications block either automatically or manually:
MOVE 'EMPDISP' TO PROGRAM-NAME.
The BIND RUN-UNIT statement is used in both the navigational and the non-navigational environments.
►►─── BIND RUN-UNIT ─┬──────────────────────────┬─────────────────────────────►
└─ FOR subschema-name ─────┘
►─┬────────────────────┬─┬────────────────────────┬──────────────────────────►
└─ DBNODE nodename ──┘ └─ DBNAME database-name ─┘
►─┬─────────────────────┬────┬────────────────────────────┬─ . ──────────────►◄
└─ DICTNODE nodename ─┘ └─ DICTNAME dictionary-name ─┘
Identifies a subschema view other than that specified in the DB clause of the SCHEMA SECTION. It must be the symbolic name of a user-defined eight-character field in variable storage.
By default, if you do not specify a subschema, the run unit uses the subschema named in the DB clause of the SCHEMA SECTION.
Note: Exercise care when using the FOR subschema-name option; improper use can lead to mismappings between the named subschema and record descriptions in variable storage.
Specifies the node where the database resides.
Either the symbolic name of a user-defined eight-character field in variable storage or the database name itself enclosed in quotation marks.
Specifies the database to be accessed by the run unit.
Either the symbolic name of a user-defined eight-character field in variable storage or the database name itself enclosed in quotation marks.
Specifies the node that controls the dictionary where the subschema resides.
Either the symbolic name of a user-defined eight-character field in variable storage or the node name itself enclosed in quotation marks.
Specifies the dictionary where the subschema resides.
Either the symbolic name of a user-defined eight-character field in variable storage or the dictionary name itself enclosed in quotation marks.
Note: The DBNODE, DBNAME, DICTNODE, and DICTNAME parameters can be overridden at runtime by the DCUF SET DBNODE/DBNAME and DCUF SET DICTNODE/DICTNAME commands.
Batch users: The DBNODE AND DBNAME parameters can be overridden at runtime if the IDMSOPTI module or the SYSCTL clause in the system generation SYSTEM statement specifies a nodename or a dbname with the ALWAYS option. For more information about the use of DBNODE, DBNAME, DICTNODE, and DICTNAME, see the System Generation Guide.
The following statement binds the run unit to the DBMS:
BIND RUN-UNIT.
After completion of the BIND RUN-UNIT function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
1400 |
The BIND RUN-UNIT statement cannot be recognized. This code usually indicates that the IDMS communications block (SUBSCHEMA-CTRL) is not aligned on a fullword boundary. |
|
1410 |
Security violation; an existing access restriction or subschema usage prohibits execution of the specified DML function. For LRF users, the subschema in use allows access to database records only. Combined with a major code of 00, this code means the program has attempted to access a database record, but the subschema in use allows access to logical records only. |
|
1417 |
The transaction manager encountered an error. See the log for additional information. |
|
1467 |
Invalid subschema load module; the subschema invoked does not match the subschema object tables. subschema object tables. |
|
1469 |
The run unit is not bound to the DBMS. This code indicates that the central version is not active, that the central version is not accepting new run units, or that the run unit's connection to the central version is broken due to timeout or other factors, as noted on the CV log. |
|
1470 |
A journal file will not open (local mode only); under OS, the most probable cause is that a DD statement for the journal file is missing in the JCL. |
|
1472 |
There is insufficient memory to dynamically load a subschema or database procedure. |
|
1473 |
The central version is not accepting new run units. |
|
1474 |
The subschema was not found in the dictionary load area or in the load library. |
|
1477 |
The run unit has been bound previously. |
|
1480 |
The node specified is not active or has been disabled. |
|
1481 |
The converted subschema requires specified database name to be in the DBNAME table. |
|
1482 |
The subschema must be named in the DBNAME table. |
|
1483 |
The available memory is insufficient to allocate native VSAM work areas. |
|
1491 |
The subschema requires a DBNAME to do the bind run unit. |
|
1492 |
No subschema areas map to DMCL. |
|
1493 |
A subschema area symbolic was not found in DMCL. |
|
1494 |
The specified dbname is neither a dbname defined in the DBNAME table, nor a SEGMENT defined in the DMCL. |
|
1495 |
The specified subschema failed DBTABLE mapping using the specified dbname. |
The BIND TASK statement initiates an CA IDMS task when the operating mode is DC-BATCH. This statement establishes communication with the DC system and, if accessing CA IDMS queues, allocates a packet-data movement buffer to contain the queue data. Once a task is started, the program can issue any number of consecutive BIND-READY-FINISH sequences.
Note: Do not issue this command in local mode.
►►─── BIND TASK ──────────────────────────────────────────────────────────────► ►─┬───────────────────────┬─ . ──────────────────────────────────────────────►◄ └─ NODENAME (nodename) ─┘
Specifies the node to which the task will be bound.
Either the symbolic name of a user-defined field that contains the nodename or the nodename itself enclosed in quotation marks. The specified node name must match the node named in the DDS statement at system generation.
The following statement establishes communication with a DC system.
BIND TASK.
After completion of the BIND TASK function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
The BIND TRANSACTION STATISTICS statement defines the beginning of a transaction for the purposes of collecting transaction statistics. CA IDMS allocates a block of storage in which to accumulate these statistics. Because this block is owned by the logical terminal associated with the current task, the BIND TRANSACTION STATISTICS statement cannot be used with nonterminal tasks.
Note: If a transaction statistics block (TSB) is already allocated for the logical terminal associated with the current task, the BIND request clears the block and writes any previously accumulated transaction statistics to the log file.
When a BIND TRANSACTION STATISTICS request is issued, the transaction is assigned a 40-character identifier; the first 32 characters are the identifier of the signed-on user (if any) and the last eight characters are the identifier of the logical terminal associated with the current task.
►►─── BIND TRANSACTION STATISTICS . ──────────────────────────────────────────►◄
The following example illustrates the BIND TRANSACTION STATISTICS statement:
BIND TRANSACTION STATISTICS.
After completion of the BIND TRANSACTION STATISTICS function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully; any existing transaction statistics block was written to the log file before being cleared |
|
3801 |
Storage for the transaction statistics block is not available; to wait would cause a deadlock |
|
3810 |
A new transaction statistics block has been allocated |
|
3831 |
Either the parameter list is invalid or no logical terminal element (LTE) is associated with the issuing task |
|
3850 |
The collection of transaction statistics or task statistics has not been enabled during system generation |
The CHANGE PRIORITY statement changes the dispatching priority of the issuing task. The new dispatching priority applies only to the current execution of the task. CHANGE PRIORITY does not relinquish control to another task and cannot be used to alter the priority of other tasks.
►►─── CHANGE PRIORITY to priority . ──────────────────────────────────────────►◄
The new dispatching priority for the issuing task.
Either the symbolic name of a user-defined field that contains the priority value or the value itself expressed as a numeric constant in the range 0 through 240.
The following example changes the dispatching priority of the issuing task to the value contained in the PRIORITY-210 field:
CHANGE PRIORITY TO PRIORITY-210.
After completion of the CHANGE PRIORITY function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
The CHECK TERMINAL statement delays task processing until a previously issued I/O request has completed.
If a READ TERMINAL, WRITE TERMINAL, or WRITE THEN READ TERMINAL request specifies the NOWAIT option, the program must issue a CHECK TERMINAL request before specifying any other I/O operation. If the I/O operation is not complete, the task execution is suspended. When the I/O operation is complete, the task resumes execution according to its established dispatching priority.
►►─── CHECK TERMINAL ─┬───────────────┬───────────────────────────────────────►
└─ GET STORAGE ─┘
►─── INTO input-data-location ─┬─ TO end-input-data-location ───────┬────────►
└─ MAX LENGTH input-data-max-length ─┘
►─┬───────────────────────────────────────────────┬─ . ──────────────────────►◄
└─ RETURN LENGTH into input-data-actual-length ─┘
Asynchronous requests only. Acquires an input buffer for the data being read into the program; CA IDMS allocates the required storage when the read operation is complete.
Specifies the 01-level WORKING-STORAGE SECTION or LINKAGE SECTION data area reserved for the input data stream.
Specifies the symbolic name of a user-defined field.
If GET STORAGE is specified, the data area reserved for the input data stream must be an unallocated 01-level LINKAGE SECTION entry. If GET STORAGE is not specified, the data area must be a previously allocated WORKING-STORAGE SECTION or LINKAGE SECTION entry.
Specifies the end of the data area reserved for the input.
Either the symbolic name of a user-defined dummy byte field or a field that contains a data item not associated with the data area reserved for the input data stream.
Defines the length, in bytes, of the data area reserved for the input data stream.
Either the symbolic name of a user-defined field that contains the length of the data area or the length itself expressed as a numeric constant.
If the input data stream is larger than the data area reserved in the WORKING-STORAGE SECTION or LINKAGE SECTION, the data stream is truncated as needed to fit the available space.
Specifies the location to return the actual length of the input data stream.
The symbolic name of a user-defined field. If the data stream has been truncated, input-data-actual-length will contain the original length before truncation.
The following statement determines whether an I/O operation is complete, acquires an input buffer, and reads 72 bytes of data into TERM-LINE:
CHECK TERMINAL GET STORAGE INTO TERM-LINE MAX LENGTH 72.
After completion of the CHECK TERMINAL function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
4519 |
The input area specified for the return of data is too small; the returned data has been truncated to fit the available space. |
|
4525 |
The output operation has been interrupted; the terminal operator has pressed ATTENTION or BREAK. |
|
4526 |
A logical error (for example, an invalid control character) has been encountered in the output data stream. |
|
4527 |
A permanent I/O error has occurred during processing. |
|
4528 |
The dial-up line for the terminal being used has been disconnected. |
|
4531 |
The terminal request block (TRB) contains an invalid field, indicating a possible error in the program's parameters. |
|
4535 |
Storage for the input buffer cannot be acquired because the specified 01-level LINKAGE SECTION entry has been allocated. |
|
4537 |
Storage for the input buffer cannot be acquired because the specified data area is defined in the WORKING-STORAGE SECTION rather than in the LINKAGE SECTION. |
|
4538 |
The specified 01-level LINKAGE SECTION entry has not been allocated and the GET STORAGE option has not been specified. No I/O has been performed. |
|
4539 |
The terminal device associated with the issuing task is out of service. |
The COMMIT statement commits changes made to the database through an individual run unit or through all database sessions associated with a task. A task-level commit also commits all changes made in conjunction with scratch, queue, and print activity.
If the commit applies to an individual run unit and the run unit is sharing its transaction with another database session, the run unit's changes may not be committed at the time the COMMIT statement is executed.
Note: For more information about the impact of transaction sharing, see the CA IDMS Navigational DML Programming Guide.
Run units (and SQL sessions) impacted by the COMMIT statement remain active after the operation is complete.
The COMMIT statement is used in both the navigational and logical record facility environments. The COMMIT TASK statement is also used in an SQL programming environment.
Use of the ALL option, as in COMMIT ALL, sets all currencies to null.
►►─── COMMIT ─┬────────┬─┬───────┬─ . ────────────────────────────────────────►◄
└─ TASK ─┘ └─ ALL ─┘
Commits the changes made by all scratch, queue, and print activity and all top-level run units associated with the current task. Its impact on SQL sessions associated with the task depends on whether those sessions are suspended and whether their transactions are eligible to be shared.
More information:
For more information about the impact of a COMMIT TASK statement on SQL sessions, see the CA IDMS SQL Programming Guide.
For more information about run units and the impact of COMMIT TASK, see the CA IDMS Navigational DML Programming Guide.
Releases all currency locks held on records in database, scratch, and queue areas associated with the issuing task (COMMIT TASK ALL) or run unit (COMMIT ALL) and sets all currencies to null.
The following statement commits changes made by the run unit through which it is issued:
COMMIT.
After completion of the COMMIT function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
5031 |
The specified request is invalid; the program may contain a logic error |
|
5097 |
An error was encountered processing a syncpoint request; check the log for details |
The CONNECT statement establishes a record occurrence as a member of a set occurrence. The specified record must be defined as an optional automatic, optional manual, or mandatory manual member of the set. Native VSAM users:. The CONNECT statement is not valid since all sets in native VSAM data sets must be defined as mandatory automatic.
Before execution of the CONNECT statement, the following conditions must be satisfied:
Following successful execution of a CONNECT statement, the specified record is current of run unit, its record type, its area, and all sets in which it currently participates.
The following figure illustrates the steps required to connect an EMPLOYEE record to an occurrence of the OFFICE-EMPLOYEE set.
To connect EMPLOYEE 459 to OFFICE 1 in the OFFICE-EMPLOYEE set, establish EMPLOYEE 459 as current of record type, locate the proper occurrence of the OFFICE record, and issue the CONNECT command.
►►─── CONNECT record-name TO set-name . ──────────────────────────────────────►◄
Specifies the record whose current occurrence is to be connected to the current occurrence of the specified set.
Must be a record included in the subschema and must be defined as an optional automatic, optional manual, or mandatory manual member of the set to which it is being connected.
Specifies the set to which the member record is to be connected.
Specifies the name of a set included in the subschema. The record is connected to the set in accordance with the ordering rules defined for that set in the schema.
The following statement connects the current EMPLOYEE record to the current occurrence of the OFFICE-EMPLOYEE set:
CONNECT EMPLOYEE TO OFFICE-EMPLOYEE.
After completion of the CONNECT function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
0705 |
The CONNECT would violate a duplicates-not-allowed option. |
|
0706 |
Currency has not been established for the named record or set. |
|
0708 |
The named record is not in the subschema. The program has probably invoked the wrong subschema. |
|
0709 |
The named record's area has not been readied in one of the update usage modes. |
|
0710 |
The subschema specifies an access restriction that prohibits connecting the named record in the named set. |
|
0714 |
The CONNECT statement cannot be executed because the named record has been defined as a mandatory automatic member of the set. |
|
0716 |
The record cannot be connected to a set in which it is already a member. |
|
0721 |
An area other than the area of the named record has been readied with an incorrect usage mode. |
|
0725 |
Currency has not been established for the named set type. |
The DC RETURN statement returns control to a program at the next higher level within a task. Additionally, you can use the DC RETURN statement to specify:
Following a DC RETURN request, control returns to the program at the next higher level within the task. If the issuing program is the highest level program, control returns to CA IDMS. Any DC RETURN statement can include a NEXT TASK CODE option to specify the next task to initiate. However, the position of the issuing program within the task governs whether the specified task will, in fact, receive control.
DC RETURN Processing
The following figure illustrates how a task is executed when DC RETURN statements within three programs specify the NEXT TASK CODE option.
Task A invokes program A. Program A links to program B, which in turn links to program C. Program C issues a DC RETURN NEXT TASK CODE 'Z' request; control returns to program B. Program B contains a DC RETURN NEXT TASK CODE 'Y' request, which takes precedence over program C's DC RETURN specification. Control returns to program A, which issues a DC RETURN NEXT TASK CODE 'X' request. Because program A is at the highest level in the task, task X will be invoked.
IDMS-DC
───────────────────────────────────────────────────────────────────────
TASK X
TASK A ┌───────────────────────────┐
───────────┬───────────▲───────────────────────────┼──────────────────
│ │ │
│ │ ┌──────▼──────┐
│ │ │ │
┌────────▼────────┐ │ │ PROGRAM X │
│ PROGRAM A │ │ │ │
│ . │ │ └─────────────┘
│ . │ │ (RETURN)
┌─┤ . ◄──┼─────────────────────────┐
│ │ DC RETURN │ │ │
│ │ NEXT TASK CODE │ │ │
│ │ X │ │ │
│ └────────┬────────┘ │ │
│ └───────────┘ │
│ │
│ │
│ │
│ │
│ │
│ (LINK B) ┌─────────────────┐ │
└───────────────────────────► PROGRAM B │ │
│ . │ │
│ . │ │
┌─┤ . │ │ (RETURN)
│ │ DC RETURN ◄──┼─────────────────┐
│ │ NEXT TASK CODE │ │ │
│ │ Y │ │ │
│ └────────┬────────┘ │ │
│ └───────────┘ │
│ │
│ │
│ (LINK C) ┌─────────────────┐ │
└───────────────────► PROGRAM C │ │
│ . │ │
│ . │ │
│ . │ │
│ DC RETURN │ │
│ NEXT TASK CODE │ │
│ Z │ │
└────────┬────────┘ │
└───────────┘
When CA IDMS receives control from the highest level program that issued a DC RETURN NEXT TASK CODE request, the specified task is executed immediately if the specified task code has been assigned the NOINPUT attribute during system generation; if the task code was assigned the INPUT attribute, the task executes only when the user presses an attention identifier (AID) key. Typical AID keys include all PA and PF keys, ENTER, and CLEAR.
►►─── DC RETURN ──────────────────────────────────────────────────────────────►
►─┬─────────────────────────────────┬────────────────────────────────────────►
└─ NEXT TASK CODE next-task-code ─┘
►─┬─────────────┬────────────────────────────────────────────────────────────►
├─ NORMAL ◄ ──┤
├─ ABORT ─────┤
├─ CONTINUE ──┤
└─ IMMEDIATE ─┘
►─┬───────────────────────────────────────────────┬──────────────────────────►
│ ┌─────────────────────────────────┐ │
└─ TIMEOUT ─▼─┬─ INTERVAL timeout-interval ─┬─┴─┘
└─ PROGRAM timeout-program ───┘
►─┬──────────────────────────────────────────────────────────────────────────►─
└─ NEXT TASK INTERVAL start-interval EVENT TYPE ─┬─ INTERNAL ─┬─────────────
└─ EXTERNAL ─┘
─►─────────────────────────┬─ . ──────────────────────────────────────────────►◄
──┬─────────────────────┬─┘
├─ EVENT ecb ─────────┤
└─ EVENT NAME ecb-id ─┘
Specifies the next task to be initiated on the same terminal.
Either the symbolic name of a user-defined field that contains the task code or the task code itself enclosed in quotation marks. The task code must be defined to the DC system under which it is running, either during system generation or at runtime.
Defines the recovery action to take within the program logic (CA IDMS recovery occurs automatically) and specifies whether to execute abend routines for higher-level programs. These options apply to DC RETURNs issued from abend routines established by SET ABEND EXIT (STAE) functions only.
Specifies to not attempt recovery and execute all abend routines established for programs at higher task levels.
This is the default.
Specifies to not attempt recovery and abort the task immediately without executing any abend routines established for programs at higher task levels.
Specifies to return control to the program that failed at an address established in the abend control element (ACE) for the program.
Is ignored when issued from ABEND routine; it is only applied when NOT issued from an ABEND routine.
Specifies the action to take if the user fails to enter data required to initiate a task. This parameter overrides resource timeout interval and program specifications established during system generation.
Specifies the time, in seconds, that can elapse before releasing the resources held by the terminal on which the task is executing.
Either the symbolic name of a user-defined PIC S9(4) COMP SYNC (halfword) field that contains the timeout interval or the interval itself expressed as a numeric constant.
Specifies the program to be invoked to handle and release resources held by the terminal on which the task is executing when the specified timeout interval has been reached.
Either the symbolic name of a user-defined field that contains the program name or the name itself enclosed in quotation marks.
The specified program must be defined to the DC system either during system generation or at runtime.
Either the symbolic name of a user-defined PIC S9(4) COMP SYNC (halfword) field that contains the start interval or the interval itself expressed as a numeric constant.
Note: When specified alone, NEXT TASK INTERVAL will cause task to be initiated after start-interval. When specified along with EVENT/EVENT NAME, task will be initiated either after start-interval or posting of the EVENT(S)/EVENT NAME(S), whichever occurs first.
Specifies events that happen either internal or external to the system.
An event that occurs within IDMS-DC, such as waiting for space in a storage pool, or waiting for a completed task.
An event that occurs outside the system's control, such as waiting for a file to be read, or waiting for an I/O to complete.
Defines one or more ECBs upon which the task will wait.
The symbolic name of a user-defined area that contains three PIC S9(8) COMP SYNC (fullword) fields. Multiple EVENT parameters must be separated by at least one blank.
Specifies the ECB upon which the task will wait.
Note: When specified alone, NEXT TASK INTERVAL will cause task to be initiated after start-interval. When specified along with EVENT/EVENT NAME, task will be initiated either after start-interval or posting of the EVENT(S)/EVENT NAME(S), whichever occurs first.
Either the symbolic name of a user-defined field that contains the ECB ID or the ID itself enclosed in quotation marks.
The following statement illustrates the use of DC RETURN. The task code associated with MENU-TASK-CODE, if defined with the INPUT parameter, will be invoked when the user next presses an AID key; if MENU-TASK-CODE is defined with the NOINPUT parameter, it will be invoked immediately.
DC RETURN NEXT TASK CODE MENU-TASK-CODE.
Because control is returned to the next-higher level, there is no need to check the ERROR-STATUS field.
The DELETE QUEUE statement deletes all or part of a queue. If only one queue record is deleted, CA IDMS maintains currency within the queue by saving the next and prior currencies of the deleted record.
►►─── DELETE QUEUE ─┬───────────────┬─┬─────────────────┬─ . ─────────────────►◄
└─ ID queue-id ─┘ └─┬─ CURRENT ◄ ─┬─┘
└─ ALL ───────┘
Specifies the queue that contains the record to be deleted.
Either the symbolic name of a user-defined field that contains the ID or the ID itself enclosed in quotation marks. If you do not specify an ID, a blank ID is assumed.
Deletes the current record of the queue associated with the requesting task.
This is the default.
Deletes all records in the queue and the queue header ID.
The following example illustrates a request to delete the current record in the RES-Q queue:
DELETE QUEUE ID 'RES-Q' CURRENT.
After completion of the DELETE QUEUE function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
4404 |
The requested queue header record cannot be found. |
|
4405 |
The requested queue record cannot be found. |
|
4406 |
No resource control element (RCE) exists for the queue record, indicating that currency has not been established. |
|
4407 |
A database error occurred during queue processing. A common cause is a DBKEY deadlock. For a PUT QUEUE operation, this code can also mean that the queue upper limit has been reached. If a database error has occurred, there are usually be other messages in the CA-IDMS/DC/UCF log indicating a problem encountered in RHDCRUAL, the internal Run Unit Manager. If a deadlock has occurred, messages DC001000 and DC001002 are also produced. |
|
4431 |
The parameter list is invalid. |
The DELETE SCRATCH statement deletes one scratch record or all records in the scratch area.
►►─── DELETE SCRATCH ─────────────────────────────────────────────────────────► ►─┬───────────────────────────┬──────────────────────────────────────────────► └─ AREA ID scratch-area-id ─┘ ►─┬───────────────────────────────┬──────────────────────────────────────────► ├─ CURRENT ◄ ───────────────────┤ ├─ FIRST ───────────────────────┤ ├─ LAST ────────────────────────┤ ├─ NEXT ────────────────────────┤ ├─ PRIOR ───────────────────────┤ ├─ ALL ─────────────────────────┤ └─ RECORD ID scratch-record-id ─┘ ►─┬───────────────────────────────────────────────┬─ . ──────────────────────►◄ └─ RETURN RECORD ID into return-scratch-record ─┘
Specifies the scratch area associated with the scratch records being deleted.
Either the symbolic name of a user-defined field that contains the scratch area ID or the ID itself enclosed in quotation marks. If you do not specify an AREA ID, an area ID of eight blanks is assumed.
Deletes the current record in the scratch area (that is, that record most recently referenced by another scratch function).
This is the default.
Deletes the first record in the specified scratch area.
Deletes the last record in the specified scratch area.
Deletes the next record in the specified scratch area.
Deletes the prior record in the specified scratch area.
Deletes all records in the specified scratch area.
Deletes the identified record.
The symbolic name of a user-defined field that contains the ID.
Specifies the location in the program in which to return the ID of the last record deleted by means of the DELETE SCRATCH function.
The symbolic name of a user-defined four-byte field.
The following example illustrates a request to delete the scratch record that is prior to the current scratch record and return the ID of the deleted record to the SCR-REC-ID field:
DELETE SCRATCH PRIOR RETURN RECORD ID INTO SCR-REC-ID.
After completion of the DELETE SCRATCH function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
4303 |
The requested scratch area ID cannot be found |
|
4305 |
The requested scratch record ID cannot be found |
|
4307 |
An I/O error has occurred during processing |
|
4331 |
The parameter list is invalid |
The DELETE TABLE statement notifies CA IDMS that the issuing task has finished using a table that has been loaded into the program pool by using the LOAD TABLE function. DELETE TABLE does not physically delete reusable tables from the program pool; rather, it decrements the in-use count maintained by CA IDMS. An in-use count of 0 signals to reuse the space occupied by the table.
►►── DELETE TABLE from 01-level-program-location . ───────────────────────────► ►─┬──────────────────────┬─┬────────────────────────────┬────────────────────► └─ DICTNODE nodename ──┘ └─ DICTNAME dictionary-name ─┘ ►─┬────────────────────────┬─ . ─────────────────────────────────────────────►◄ └─ LOADLIB library-name ─┘
The LINKAGE SECTION entry of the 01-level record area specified in the associated LOAD TABLE request.
Specifies the node that controls the dictionary where the subschema containing the table resides.
Specifies the symbolic name of a user-defined eight-character field in variable storage.
Specifies the dictionary where the subschema containing the table resides.
Specifies the symbolic name of a user-defined eight-character field in variable storage.
Specifies the load library containing the table.
Specifies the symbolic name of a user-defined eight-character field in variable storage.
The following example releases a previously loaded table from the location in variable storage identified by RATE-TABLE:
DELETE TABLE FROM RATE-TABLE.
After completion of the DELETE TABLE function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
3433 |
The specified table was not loaded by the task |
The DEQUEUE statement releases resources acquired by the issuing task with an ENQUEUE request. Acquired resources not released explicitly with a DEQUEUE request are released automatically at task termination.
►►─── DEQUEUE ─┬─ ALL ────────────────────────────────────────────┬─ . ───────►◄
│ ┌──────────────────────────────────────────────┐ │
└─▼─ NAME resource-id LENGTH resource-id-length ─┴─┘
Releases all resources acquired by the issuing task by means of ENQUEUE requests.
Specifies a resource to be dequeued.
Multiple resource specifications must be separated by at least one blank.
The symbolic name of a user-defined field that contains the resource ID.
Specifies the length of the resource.
Either the symbolic name of a PIC S9(8) COMP SYNC (fullword) field that contains the length of the resource ID or the length itself expressed as a numeric constant.
DEQUEUE PAYROLL-LOCK
LENGTH 16.
After completion of the DEQUEUE function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
3913 |
At least one resource ID cannot be found; all resources that were located have been dequeued |
|
3931 |
The parameter list is invalid. |
The DISCONNECT statement cancels the current membership of a record occurrence in a set occurrence. The named record must be defined as an optional member of the named set. Native VSAM users:. The DISCONNECT statement is not valid since all sets in native VSAM data sets must be defined as mandatory automatic.
Before execution of the DISCONNECT statement, the following conditions must be satisfied:
Following successful execution of the DISCONNECT statement, the named record can no longer be accessed through the set for which membership was cancelled. The disconnected record can still be accessed either by means of a complete scan of the area in which it participates or directly through its db-key, if known. A disconnected record can also be accessed either through any other sets in which it participates as a member or if it has a location mode of CALC.
A successfully executed DISCONNECT statement nullifies currency in the specified set. However, next, prior, and owner of set are maintained, enabling continued access within the set. The disconnected record is current of run unit, its record type, its area, and any other sets in which it participates.
The following figure illustrates the steps required to disconnect an EMPLOYEE record from an occurrence of the OFFICE-EMPLOYEE set.
To disconnect EMPLOYEE 4 from the OFFICE 1 of the OFFICE-EMPLOYEE set, enter the database on OFFICE, establish EMPLOYEE 4 as current of the EMPLOYEE record type, and disconnect it from the OFFICE-EMPLOYEE set.
►►─── DISCONNECT record-name FROM set-name . ─────────────────────────────────►◄
Specifies the record to disconnect from the named set.
Must be a record included in the subschema and must be defined as an optional member of the specified set.
Specifies the set from which the named record will be disconnected.
Specifies the name of a set included in the subschema.
The following statement disconnects the current EMPLOYEE record from the OFFICE-EMPLOYEE set:
DISCONNECT EMPLOYEE FROM OFFICE-EMPLOYEE.
After completion of the DISCONNECT function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
1106 |
Currency has not been established for the named record |
|
1108 |
The named record is not in the subschema. The program has probably invoked the wrong subschema |
|
1109 |
The named record's area has not been readied in one of the update usage modes |
|
1110 |
The subschema specifies an access restriction that prohibits use of the DISCONNECT statement |
|
1115 |
The DISCONNECT statement cannot be executed because the named record has been defined as a mandatory member of the set |
|
1121 |
An area other than the area that contains the named record has been readied with an incorrect usage mode |
|
1122 |
The named record is not currently a member of the specified set |
The END LINE TERMINAL SESSION statement terminates the current line I/O session. All output data lines that remain in the current buffer and all pages queued for asynchronous I/O operations are deleted.
►►─── END LINE TERMINAL SESSION . ────────────────────────────────────────────►◄
The following statement terminates a line mode I/O session:
END LINE TERMINAL SESSION.
There are no status codes associated with the END LINE TERMINAL SESSION command.
The END TRANSACTION STATISTICS statement defines the end of a transaction. The transaction typically ends when the issuing task terminates. Optionally, END TRANSACTION STATISTICS can be used to write the transaction statistics block (TSB) to the DC system log file and to return the TSB to a preallocated location in variable storage. You can define the length of the TSB.
►►─── END TRANSACTION STATISTICS ─────┬───────────┬────────────────────────────►
├─ WRITE ◄ ─┤
└─ NOWRITE ─┘
►───┬──────────────────────────────────┬──────────────────────────────────────►
└─ INTO return-stat-data-location ─┘
►───┬─────────────────────────────────┬────────────────────────────────────;──►◄
└─ LENGTH ─┬─ 388 ◄───────────┬───┘
└─ len-return-TSB ─┘
Specifies whether the TSB is written to the DC system log file when the task terminates.
Default: WRITE.
Specifies the WORKING-STORAGE SECTION or LINKAGE SECTION data area into which to return the TSB.
A fullword-aligned 388-byte field (you can customize the length using the LENGTH parameter).
Specifies the length of the returned TSB. To retrieve all statistics including the DC extended statistics section that records CPU times in the Time of Day (TOD) format, specify LENGTH as 560.
Specifies either the symbolic name of a user-defined field that contains the length of the TSB, or the length expressed as a numeric constant.
Limits: Integer of 388 or greater
Default: If you do not specify len-return-TSB, the first 388 bytes of the TSB are returned.
The following statement illustrates a request to end a transaction, write statistics to the log file, and return a copy of the TSB to the STATISTICS-BLOCK field:
END TRANSACTION STATISTICS WRITE INTO STATISTICS-BLOCK.
After completion of the END TRANSACTION STATISTICS function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
3801 |
Storage for the transaction statistics block is not available; to wait would cause a deadlock. |
|
3813 |
No transaction statistics block exists; a BIND TRANSACTION STATISTICS request has not been issued. |
|
3831 |
Either the parameter list is invalid or no logical terminal element (LTE) is associated with the issuing task. |
|
3850 |
The collection of transaction statistics or task statistics has not been enabled during system generation. |
The ENDPAGE statement terminates a map paging session, clears the scratch record for the session, and clears the map paging options for the completed session. A STARTPAGE/ENDPAGE pair encloses commands that handle a pageable map at runtime. The STARTPAGE command is discussed later in this chapter.
►►─── ENDPAGE session . ──────────────────────────────────────────────────────►◄
The following statement ends a map paging session:
ENDPAGE session.
After completion of the ENDPAGE function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
The ENQUEUE statement acquires or tests the availability of a resource or list of resources. Resources are defined during installation and system generation and typically include storage areas, common routines, queues, and processor time.
An enqueued resource can be exclusive or shared:
Note: An exclusive ENQUEUE request prohibits another task from enqueuing a resource by name; however, it does not prohibit the use of the resource by another task. Therefore, to effect true resource protection, you must enqueue and dequeue resources consistently.
►►─── ENQUEUE ─┬──────────┬───────────────────────────────────────────────────►
├─ WAIT ◄ ─┤
├─ NOWAIT ─┤
└─ TEST ───┘
┌─────────────────────────────────────────────────────────────┐
►─▼─ NAME resource-id LENGTH resource-length ─┬───────────────┬┴─ . ────────►◄
├─ EXCLUSIVE ◄ ─┤
└─ SHARED ──────┘
Specifies to wait for all resources to be freed, if it cannot service the request immediately.
This is the default.
Specifies to not wait to acquire resources that are not currently available. If NOWAIT is specified, the program should check the ERROR-STATUS field in the IDMS-DC communications block to determine if the function has been completed. If the ERROR-STATUS value is 3901, indicating that a resource could not be obtained immediately, the request has not been serviced and the program should perform alternative processing before reissuing the NOWAIT request.
Specifies to test the availability of the specified resources. If TEST is specified, the program should check the ERROR-STATUS field in the IDMS-DC communications block to determine the outcome of the test.
Specifies the ID associated with a resource.
Multiple resource specifications must be separated by at least one blank.
Specifies the symbolic name of a user-defined field that contains the name of the resource. The resource name is a 1–256 byte character string used to identify the resource that an enqueue is to be set or tested with. Any character string can be defined as long as all programs that access the resource use the same name, and as long as the name is unique relative to all other names used to identify other resources within the CV.
Specifies the length of the resource.
Either the symbolic name of a user-defined field that contains the length of the resource ID or the length itself expressed as a numeric constant.
Assigns the exclusive attribute to the named resource.
This is the default.
Assigns the shared attribute to the named resource.
The statements below illustrate the use of the ENQUEUE statement:
The following statement enqueues the CODE-VALUE and PAYROLL-LOCK resources. CODE-VALUE is reserved for the issuing task's exclusive use; PAYROLL-LOCK can be shared.
ENQUEUE WAIT NAME CODE-VALUE LENGTH 10 NAME PAYROLL-LOCK LENGTH 16 SHARED.
The following statement tests the availability of the resource whose identifier is contained in the RESOURCE-NAME field:
ENQUEUE TEST NAME RESOURCE-NAME LENGTH RESOURCE-LENGTH.
After completion of an ENQUEUE function to acquire resources, the ERROR-STATUS field in the IDMS DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
3901 |
At least one of the requested resources cannot be enqueued immediately; to wait would cause a deadlock. No new resources have been acquired. |
|
3908 |
At least one of the requested exclusive resources is currently owned by another task. No new resources have been acquired. |
|
3931 |
Parameter list is invalid. |
After completion of an ENQUEUE function to test resources, the ERROR-STATUS field in the IDMS DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
All requested resources are available. |
|
3908 |
At least one of the tested resources is already owned by another task. |
|
3909 |
At least one of the tested resources is not yet owned by another task and is available to the issuing task. |
|
3931 |
Parameter list is invalid. |
The ERASE statement performs the following functions:
ERASE is a two-step procedure that first cancels the existing membership of the named record in specific set occurrences and then releases for reuse the space occupied by the named record and its db-key. Erased records are unavailable for further processing by any DML statement.
Before execution of the ERASE statement, the following conditions must be satisfied:
Following successful execution of an ERASE statement, currency is nullified for all record types involved in the erase both explicitly and implicitly. Run unit and area currency remain unchanged. Next, prior, and owner currencies are preserved for sets from which the last record occurrence was erased. These currencies enable you to retrieve the next or prior records within the area or the next, prior, or owner records within the set in which the erased record participated. An attempt to retrieve erased records results in a non-zero status condition.
►►─── ERASE record-name ─┬───────────────────────┬─── . ──────────────────────►◄
├─ PERMANENT MEMBERS ───┤
├─ SELECTIVE MEMBERS ───┤
└─ ALL MEMBERS ─────────┘
Specifies the name of the record to be erased. It must be a record included in the subschema. The current of record-name must be current of run unit.
Unless PERMANENT, SELECTIVE, or ALL qualification follows, a non-zero status condition results if the named record is the owner of any nonempty set occurrences.
Native VSAM users: ERASE record-name is the only form of the ERASE statement valid for records in a native VSAM KSDS or RRDS; the ERASE statement is not valid for a native VSAM ESDS.
Erases the specified record and all mandatory member record occurrences owned by the specified record. Optional member records are disconnected. If any of the erased mandatory members are themselves the owner of any set occurrences, the ERASE statement is executed on such records as if they were directly the object record of an ERASE PERMANENT statement (that is, all mandatory members of such sets are also erased). This process continues until all direct and indirect members have been processed.
Erases the specified record and all mandatory member record occurrences owned by the specified record. Optional member records are erased if they do not currently participate as members in other set occurrences. All erased member records that are themselves the owners of any set occurrences are treated as if they were the object of an ERASE SELECTIVE statement.
Erases the specified record and all mandatory and optional member record occurrences owned by the specified record. All erased member records that are themselves the owners of any set occurrences are treated as if they were the object record of an ERASE ALL statement.
Use of the ERASE Statement
The following figure illustrates use of the three parameters of the ERASE statement.
The outcome of the ERASE statement varies based on the qualifier specified (PERMANENT, SELECTIVE, or ALL). Although all three qualifiers cause all mandatory members owned by the specified record to be erased, they differ in their effect on optional members.
Because the sample employee database provides no appropriate examples of these parameters, this figure and the one after use a sample high school database instead.
ERASE Currency
The following figure shows the effect each of the parameters has on currency.
After completion of the ERASE function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
0203 |
Invalid currency for the named record to ERASE. This can only occur when a run unit is sharing a transaction with other database sessions. The 03 minor status is returned if the run unit tries to erase a record using a currency that has been invalidated because of changes made by another database session that is sharing the same transaction. |
|
0208 |
The object record is not in the specified subschema. |
|
0209 |
The named record's area has not been readied in one of the three update usage modes. |
|
0210 |
The subschema specifies an access restriction that prohibits use of the ERASE statement. For SPF users, this code can also indicate use of an invalid form of the ERASE statement. |
|
0213 |
A current record of run unit has either not been established or has been nullified by a previous ERASE statement. |
|
0217 |
A db-key has been encountered that contains a long-term permanent lock. |
|
0220 |
The current record of run unit is not the same record type as the named record. |
|
0221 |
An area other than the area of the specified record has been readied with an incorrect usage mode. |
|
0225 |
Currency has not been established. |
|
0226 |
A broken chain has been encountered in the process of executing an ERASE ALL, PERMANENT, or SELECTIVE. |
|
0230 |
An attempt has been made to erase the owner record of a nonempty set. |
|
0233 |
Either erasure of the record occurrence is not allowed in this subschema or all sets in which the record participates have not been included in the subschema. |
|
0260 |
A record occurrence has been encountered whose type is inconsistent with the set named in the ERROR-SET field of the IDMS communications block; probable causes include: a broken chain and improper database description. |
|
0261 |
The record cannot be erased because of broken chains in the database. |
The ERASE statement deletes a logical-record occurrence. The ERASE statement does not necessarily result in the deletion of all or any of the database records used to create the specified logical record; the path selected to service an ERASE logical-record request performs whatever database access operations the DBA has specified to service the request. For example, if a DEPARTMENT loses an employee, the EMP-JOB-LR logical record that contains information about that employee would be erased. However, only the information about the former employee would be erased from the database, not all the information about the department; that is, EMPLOYEE information would be erased, but not DEPARTMENT, JOB, or OFFICE information.
LRF uses field values present in the variable-storage location reserved for the logical record to update the database. You can specify an alternative storage location from which LRF is to take field values to make the appropriate updates to the database.
►►─── ERASE logical-record-name ──────────────────────────────────────────────► ►─┬────────────────────────────────────┬─────────────────────────────────────► └─ FROM alt-logical-record-location ─┘ ►─┬────────────────────────────┬─────────────────────────────────────────────► └─ WHERE boolean-expression ─┘ ►─┬───────────────────────────────────────┬─ . ──────────────────────────────►◄ └─ ON path-status imperative-statement ─┘
Specifies the name of the logical record to erase. The logical record must be defined in the subschema. Unless you specify FROM, LRF uses field values present in the variable-storage location reserved for the logical record to make any necessary updates to the database.
Names an alternative variable-storage location from which LRF is to obtain field values to perform the appropriate database updates in response to this request. When erasing a logical record that has previously been retrieved into an alternative storage location, use the FROM clause to name the same location specified in the OBTAIN request. The alternate record location must be defined in the WORKING-STORAGE/LINKAGE SECTION.
Specifies the selection criteria to be applied to the specified logical record. For details on coding this clause, see Logical-Record Clauses at the end of this chapter.
Specifies the action to be taken if path-status is returned to the LR-STATUS field in the LRC block. For details on coding this clause, see Logical-Record Clauses at the end of this chapter.
The following example illustrates a request to erase all occurrences of a former employee's EMP-INSURANCE-LR logical record; the DBA-designated path status ALL-ERASED indicates that all occurrences of the EMP-INSURANCE-LR logical record have been erased.
ERASE EMP-INSURANCE-LR WHERE EMP-ID-0415 EQ '0316' ON ALL-ERASED PERFORM EMP-INS-DELETION-RPT.
ERASE EMP-INSURANCE-LR
As defined by the DBA, the ERASE EMP-INSURANCE-LR path group logically deletes all of the specified EMP-INSURANCE-LR occurrences but physically deletes only the COVERAGE records, as illustrated by the following figure.
The FIND statement locates a record occurrence in the database; the OBTAIN statement locates a record and moves the data associated with the record to the record buffers. Because the FIND and OBTAIN command statements have identical formats, they are discussed together. The six formats of the FIND/OBTAIN statement are as follows:
You can place locks on located record occurrences by using the KEEP clause of a FIND/OBTAIN statement. The KEEP clause sets a shared or exclusive lock:
Note: For more information about record locks, see KEEP CURRENT.
Each format of the FIND/OBTAIN statement is discussed separately on the following pages.
The FIND/OBTAIN CALC/DUPLICATE statement locates a record based on the value of an element defined as a CALC key in the record. The specified record must be stored in the database with a location mode of CALC. Before issuing the FIND/OBTAIN CALC/DUPLICATE statement, you must initialize a field in program variable storage with the CALC-key value.
You can use the DUPLICATE option to access duplicate records with the same CALC-key value as the record that is current of record type, provided that a FIND/OBTAIN CALC statement has previously accessed an occurrence of the same record type.
Following successful execution of a FIND/OBTAIN CALC/DUPLICATE statement, the accessed record becomes the current record of run unit, its record type, its area, and all sets in which it currently participates as member or owner.
►►─┬─ FIND ───┬─┬────────────────────────┬─┬─┬─ CALC ─┬──┬── record-name . ───►◄
└─ OBTAIN ─┘ └─ KEEP ─┬─────────────┬─┘ │ └─ ANY ──┘ │
└─ EXCLUSIVE ─┘ └─ DUPLICATE ─┘
Places a shared lock on the accessed record.
Places an exclusive lock on the accessed record.
Locates the first or only occurrence of the specified record type whose CALC key matches the value of the CALC data item in program variable storage.
CALC and ANY are synonyms and can be used interchangeably.
Locates the next record with the same CALC key value as the current of the specified record type. Use of the DUPLICATE option requires prior selection of an occurrence of the same record type with the CALC option. If the value of the CALC key in variable storage is not equal to the CALC-key field of the current of record type, a status code of 0332 is returned.
The name of the record type to be located.
To retrieve an occurrence of the EMPLOYEE record by using the FIND/OBTAIN CALC/DUPLICATE statement, you must first initialize the variable-storage field that contains the CALC control element. The following statements initialize the CALC field EMP-ID-0415 and retrieve an occurrence of the EMPLOYEE record:
MOVE EMP-ID-IN TO EMP-ID-0415. OBTAIN CALC EMPLOYEE.
After completion of the FIND/OBTAIN CALC/DUPLICATE function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
0301 |
The area in which the named record participates has not been readied. |
|
0306 |
A successful FIND/OBTAIN CALC has not yet been executed (applies to the DUPLICATE option only). |
|
0308 |
The named record is not in the subschema. The program probably invoked the wrong subschema. |
|
0310 |
The subschema specifies an access restriction that prohibits retrieval of the named record. |
|
0318 |
The record has not been bound. |
|
0326 |
Either the record or cannot be found or no more duplicates exist for the named record. |
|
0331 |
The retrieval statement format conflicts with the record's location mode. |
|
0332 |
The value of the CALC data item in program variable storage does not equal the value of the CALC data item in the current record (applies to the DUPLICATE option only). |
|
0364 |
The CALC control element has not been described correctly either in the program or in the subschema. |
|
0370 |
A database file will not open properly. |
If the FIND/OBTAIN statement includes an explicit KEEP: 03 is the major code returned if an error occurs during FIND processing, 06 if the error occurs during KEEP processing.
The FIND/OBTAIN CURRENT statement locates the record that is current of its record type, set, or area. This form of the FIND/OBTAIN statement is an efficient means of establishing the appropriate record as current of run unit before executing a DML statement that uses run-unit currency (for example, ACCEPT, IF, GET, MODIFY, ERASE).
Following successful execution of a FIND/OBTAIN CURRENT statement, the accessed record is current of run unit, its record type, its area, and all sets in which it currently participates as member or owner.
►►─┬─ FIND ───┬┬───────────────────────┬─ CURRENT ─┬────────────────────┬─ . ─►◄
└─ OBTAIN ─┘└─ KEEP ─┬─────────────┬┘ ├─ record-name ──────┤
└─ EXCLUSIVE ─┘ ├─ WITHIN set-name ──┤
└─ WITHIN area-name ─┘
Places a shared lock on the accessed record.
Places an exclusive lock on the accessed record.
Locates the current record occurrence of a specified record type, set, or area.
Accesses the current record of the specified record type.
Accesses the current record of the specified set.
Accesses the current record of the specified area.
Using the FIND/OBTAIN CURRENT Statement
The following figure illustrates use of the FIND/OBTAIN CURRENT statement to establish the proper record as current of run unit before the record is modified.
Enter the database on DEPARTMENT 5100 by using CALC retrieval. Then examine EMPLOYEE 466 by using within set retrieval and obtain further information from its owner OFFICE record (OFFICE 8). OFFICE 8 becomes current of run unit. Before modifying EMPLOYEE 466, you must issue the FIND CURRENT statement to reestablish EMPLOYEE 466 as current of run unit.
For a complete description of the MODIFY statement and its use, see MODIFY.
After completion of the FIND/OBTAIN CURRENT function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
0301 |
The area in which the named record participates has not been readied. |
|
0303 |
Invalid currency for a record to be retrieved on a FIND. This can only occur when a run unit is sharing a transaction with other database sessions. The 03 minor status is returned if the run unit tries to find a record using a currency that has been invalidated because of changes made by another database session that is sharing the same transaction. |
|
0306 |
Currency has not been established for the named record, set, or area. |
|
0308 |
The named record or set is not in the subschema. The program has probably invoked the wrong subschema. |
|
0310 |
The subschema specifies an access restriction that prohibits retrieval of the named record. |
|
0313 |
A current record of run unit either has not been established or has been nullified by a previous ERASE statement. |
|
0323 |
The specified area name has not been included in the subschema invoked. |
If the FIND/OBTAIN statement includes an explicit KEEP: 03 is the major code returned if an error occurs during FIND processing, 06 if the error occurs during KEEP processing.
The FIND/OBTAIN DB-KEY statement locates a record occurrence directly using a database key that has been stored previously by the program. The DML ACCEPT statement, explained earlier in this chapter, or the COBOL MOVE statement can be used to save a db-key. Any record in the program's subschema can be accessed directly in this manner, regardless of its location mode.
Native VSAM users: This statement is not valid for accessing data records in a native VSAM key-sequenced data set (KSDS).
After successful execution of a FIND/OBTAIN DB-KEY statement, the accessed record becomes the current record of run unit, its record type, its area, and all sets in which it currently participates as member or owner. In addition, the RECORD-NAME field of the IDMS communications block is updated with the name of the accessed record.
Note that currency is not used to determine the specified record of the FIND/OBTAIN DB-KEY statement; the record is identified by its db-key and, optionally, by its record type.
►►─┬─ FIND ───┬─┬────────────────────────┬───────────────────────────────────►
└─ OBTAIN ─┘ └─ KEEP ─┬─────────────┬─┘
└─ EXCLUSIVE ─┘
►─┬─ DB-KEY is db-key ─┬───────────────────────┬─┬──────────────────────────►◄
│ └─ PAGE-INFO page-info ─┘ │
└─┬────────────┬─ DB-KEY is db-key ────────────┘
└─ rec-name ─┘
Places a shared lock on the accessed record.
Places an exclusive lock on the accessed record.
Locates a record directly by using a db-key value contained in program variable storage.
A field that identifies the location within program variable storage that contains a db-key previously saved by the program.
If a record name has been specified, db-key must contain the db-key of an occurrence of the named record type. If a record name has not been specified, db-key can contain the db-key of an occurrence of any record type in the subschema.
Specifies page information that is used to determine the area with which the dbkey is associated. If not specified, the page information associated with the record that is current of rununit is used.
Note: Page information is only used if the subschema includes areasthat have mixed page groups; otherwise, it is ignored.
A four-byte field that may be defined either as a group field or as a fullword field (PIC S9(8) COMP). Identifies the location in variable storage that contains the page information previously saved by the program.
Page information is returned in the PAGE-INFO field in the subschema control area if the subschema includes areas in mixed page groups. Page information may also be returned using an ACCEPT PAGE-INFO statement.
The record type of the requested record. Rec-name must name a record that is included in the subschema.
The following statement locates the occurrence of the HOSPITAL-CLAIM record whose db-key matches the value of a field in program variable storage called SAVED-KEY:
FIND HOSPITAL-CLAIM DB-KEY IS SAVED-KEY.
The located record becomes current of run unit, current of the HOSPITAL-CLAIM record type, current of the INS-DEMO-REGION area, and current of the COVERAGE-CLAIMS set.
After completion of the FIND/OBTAIN DB-KEY function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
0301 |
The area in which the named record participates has not been readied. |
|
0302 |
The db-key is inconsistent with the area in which the record is stored. Either the db-key has not been initialized properly or the record name is incorrect. |
|
0303 |
Invalid currency for a record to be retrieved on a FIND. This can only occur when a run unit is sharing a transaction with other database sessions. The 03 minor status is returned if the run unit tries to find a record using a currency that has been invalidated because of changes made by another database session that is sharing the same transaction. |
|
0308 |
The named record is not in the subschema. The program has probably invoked the wrong subschema. |
|
0310 |
The subschema specifies an access restriction that prohibits retrieval of the named record. |
|
0326 |
The record cannot be found; record occurrence not correct type. |
|
0370 |
A database file will not open properly. |
|
0371 |
The requested page cannot be found in the DMCL. |
If the FIND/OBTAIN statement includes an explicit KEEP: 03 is the major code returned if an error occurs during FIND processing, 06 if the error occurs during KEEP processing.
The FIND/OBTAIN OWNER statement locates the owner record of the current occurrence of a set. This statement can be used to retrieve the owner record of any set whether or not that set has been assigned owner pointers.
Native VSAM users: The FIND/OBTAIN OWNER statement is not valid since owner records are not defined in native VSAM data sets.
In order to execute a FIND/OBTAIN OWNER statement, currency must be established for the specified set.
Note: When a record declared as an optional or manual member of a set is retrieved, it is not established as current of set if it is not currently connected to the specified set. A subsequent attempt to retrieve the owner record will locate instead the owner of the current record of set. In such cases, you should determine whether the retrieved record is actually a member in the specified set before executing the FIND/OBTAIN OWNER statement. The IF MEMBER statement, explained later in this chapter, can be used for this purpose.
Following successful execution of a FIND/OBTAIN OWNER statement, the accessed record becomes the current record of run unit, its record type, its area, and all sets in which it currently participates as member or owner. If the current record of set is the owner record when the statement is executed, currency within the specified set remains unchanged.
►►─┬─ FIND ───┬─┬────────────────────────┬─ OWNER WITHIN set-name . ──────────►◄
└─ OBTAIN ─┘ └─ KEEP ─┬─────────────┬─┘
└─ EXCLUSIVE ─┘
Places a shared lock on the accessed record.
Places an exclusive lock on the accessed record.
Locates the owner record of the specified set.
Specifies the set whose owner record is to be retrieved.
The name of a set included in the subschema.
Using the FIND/OBTAIN OWNER Statement to Move Through the Database
The following figure illustrates use of the FIND/OBTAIN OWNER statement.
After completion of the FIND/OBTAIN OWNER function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
0301 |
The area in which the object record participates has not been readied. |
|
0303 |
Invalid currency for a record to be retrieved on a FIND. This can only occur when a run unit is sharing a transaction with other database sessions. The 03 minor status is returned if the run unit tries to find a record using a currency that has been invalidated because of changes made by another database session that is sharing the same transaction. |
|
0306 |
Currency has not been established for the record, set, or area. |
|
0308 |
The named set is not in the subschema. The program has probably invoked the wrong subschema. |
|
0310 |
The subschema specifies an access restriction that prohibits retrieval of the object record. |
|
0360 |
A record occurrence has been encountered whose record type is not a member or owner of the set as it is defined in the subschema. |
|
0370 |
A database file will not open properly. |
If the FIND/OBTAIN statement includes an explicit KEEP: 03 is the major code returned if an error occurs during FIND processing, 06 if the error occurs during KEEP processing.
The FIND/OBTAIN WITHIN SET USING SORT KEY statement locates a member record in a sorted set. Sorted sets are ordered in ascending or descending sequence based on the value of a sort-control element in each member record. The search begins with either the current of set or the owner of the current of set and always proceeds through the set in the next direction.
Before issuing this statement, you must initialize the sort control element in program variable storage. The record occurrence selected will have a key value equal to the value of the sort control element. If more than one record occurrence contains a sort key equal to the key value in variable storage, the first such record will be selected.
In a batch environment, sorted sets can be processed more efficiently by sorting the input transactions.
Following successful execution of a FIND/OBTAIN WITHIN SET USING SORT KEY statement, the accessed record becomes current of run unit, its record type, its area, and all sets in which it currently participates as member or owner. If a member record with the requested sort-key value is not found, the current of set is nullified but the next of set and prior of set are maintained. The next of set is the member record with the next higher sort-key value (or next lower for descending sets) than the requested value; the prior of set is the member record with the next lower value (or higher for descending sets) than requested. Because these currencies are maintained, the program can walk the set to do a generic search on the sort-key value.
►►─┬─ FIND ───┬─┬────────────────────────┬─ record-name WITHIN set-name ──────►
└─ OBTAIN ─┘ └─ KEEP ─┬─────────────┬─┘
└─ EXCLUSIVE ─┘
►─┬───────────┬─ USING sort-key ── . ────────────────────────────────────────►◄
└─ CURRENT ─┘ └─;─┘
Places a shared lock on the accessed record.
Places an exclusive lock on the accessed record.
Specifies the record type to locate.
Specifies the set to be searched.
Unless you specify CURRENT, the search begins with the owner of the specified set.
The name of a sorted set included in the subschema.
Indicates that the search begins with the currencies already established for the specified set.
If the key value for the record that is current of set is higher than the key value of the requested record (assuming ascending set order), a non-zero status condition results. In a descending set order, if the key value for the record that is current of set is lower than the key value of the requested record, a non-zero status condition results.
Specifies the sort control element to be used in searching the sorted set.
The symbolic name of a field defined in working storage that contains the value of the sort control element.
Note: Due to the architecture of the client interface for CA IDMS, 256 bytes will be moved regardless of the actual length of the working storage sort key. This additional storage should be accounted for in order to avoid potential program exceptions that can occur. While these exceptions are rare, they are more probable if the sort-key is defined in a FILE or LINKAGE SECTION definition. To avoid this problem, it is recommended that the sort-key be defined in the program's WORKING STORAGE SECTION, padded to a full 256 bytes; and moved in and out of the FILE or LINKAGE SECTION fields.
Note: The value coded for sort-key can only specify a single field name. If the sort key is comprised of multiple elementary fields, the value coded should be a group-level name. The elementary fields that make up the group element must be in the same sequence as defined for the corresponding fields in the database set's schema definition. The data formats for the individual elementary fields must also match the formats of the corresponding fields within the database record.
Note: A period or semicolon is required to terminate the statement unless an ON clause has been coded.
Here is an example of OBTAIN RECA WITHIN RECA-SET USING RECA-KEY. The record's sort key would be defined as follows in the WORKING-STORAGE SECTION:
01 RECA-KEY.
02 RECA-FIELD1 PIC X(10).
02 RECA-FIELD2 PIC X(10).
It should be changed to:
01 RECA-KEY.
02 RECA-FIELD1 PIC X(10).
02 RECA-FIELD2 PIC X(10).
02 FILLER PIC X(236).
The following example illustrates the use of a FIND/OBTAIN WITHIN SET USING SORT KEY statement. Assume that the SKILL-NAME-NDX set is ordered in ascending sequence based on the value stored in SKILL-NAME-0455 in each SKILL record occurrence. Retrieval of a SKILL record with a skill name equal to PL/I is accomplished by the following statements:
MOVE 'PL/I' TO SKILL-NAME-0455.
FIND SKILL WITHIN SKILL-NAME-NDX
USING SKILL-NAME-0455.
After completion of the FIND/OBTAIN WITHIN SET USING SORT KEY function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
0301 |
The area in which the named record participates has not been readied. |
|
0303 |
Invalid currency for a record to be retrieved on a FIND. This can only occur when a run unit is sharing a transaction with other database sessions. The 03 minor status is returned if the run unit tries to find a record using a currency that has been invalidated because of changes made by another database session that is sharing the same transaction. |
|
0306 |
Currency has not been established for the named set. |
|
0308 |
Either the named record or set is not in the subschema or the named record is not a member of the named set. The program has probably invoked the wrong subschema. |
|
0310 |
The subschema specifies an access restriction that prohibits retrieval of the named record. |
|
0326 |
The record cannot be found. |
|
0331 |
The retrieval statement format conflicts with the record's location mode. |
|
0360 |
A record occurrence has been encountered whose record type is not a member or owner of the set as it is defined in the subschema. |
|
0370 |
A database file will not open properly. |
If the FIND/OBTAIN statement includes an explicit KEEP: 03 is the major code returned if an error occurs during FIND processing, 06 if the error occurs during KEEP processing.
The FIND/OBTAIN WITHIN SET/AREA statement locates records either logically, based on set relationships, or physically, based on database location. The formats of this statement allow you either to access serially each record in a set or area or to select specific occurrences of a given record type within the set or area.
The following rules apply to the selection of member records within a set:
Note: If OBTAIN has been specified, the contents of the owner record are not moved to program variable storage (that is, OBTAIN under these circumstances is treated as a FIND).
Native VSAM users:.When an end-of-set condition occurs, all currencies remain unchanged.
The following rules apply to the selection of records within an area:
Following successful execution of a FIND/OBTAIN WITHIN SET/AREA statement, the accessed record becomes the current record of run unit, its record type, its area, and all sets in which it currently participates as member or owner.
When an end-of-set condition occurs selecting records within a set, the owner record occurrence of the set becomes the current record of run unit, its record type, its area, and only the set involved in this operation. Currency of other sets in which the specified record participates as owner or member remains unaffected.
►►─┬─ FIND ───┬─┬────────────────────────┬─┬─ NEXT ───┬───────────────────────►
└─ OBTAIN ─┘ └─ KEEP ─┬─────────────┬─┘ ├─ PRIOR ──┤
└─ EXCLUSIVE ─┘ ├─ FIRST ──┤
├─ LAST ───┤
└─ number ─┘
►─┬───────────────┬─ WITHIN ─┬─ set-name ──┬─ . ─────────────────────────────►◄
└─ record-name ─┘ └─ area-name ─┘
Places a shared lock on the accessed record.
Places an exclusive lock on the accessed record.
Accesses the next record in the specified set or area relative to the current record.
Accesses the prior record in the specified set or area relative to the current record. The specified set must have prior pointers.
Accesses the first record in the specified set or area.
Accesses the last record in the specified set or area. The specified set must have prior pointers.
Accesses the indicated record number in the specified set or area. Number must either be a non-zero number or the symbolic name of a numeric field that contains a non-zero value. If the number is negative, the specified set must have prior pointers.
Specifies that within a set or area, only occurrences of the named record type will be accessed. Record-name must be defined as a member of the specified set or contained within the specified area.
Locates a record based on its location within a set or area.
set-name Specifies the set to be searched. The set must be included in the subschema.
area-name Specifies the area to be searched. The area must be included in the subschema.
Native VSAM users:.FIRST, LAST, and sequence options are not valid for a native VSAM KSDS with spanned records.
Retrieval of Records in an Occurrence of the DEPT-EMPLOYEE Set
The following figure illustrates the retrieval of records within an occurrence of the DEPT-EMPLOYEE set.
The FIND CALC statement establishes currency in the DEPT-EMPLOYEE set. Member EMPLOYEE records are then retrieved by a series of OBTAIN WITHIN SET statements. EMPLOYEE 106 is the last record in the set and the next OBTAIN statement returns an end-of-set condition, positioning run unit currency at the owner of the set, DEPARTMENT 2000.
Retrieving Records in Area Containing Multiple Record Types
The following figure illustrates special considerations relating to the retrieval of records within an area that contains multiple record types.
In this example, a sweep of the EMP-DEMO-REGION is performed, retrieving sequentially each EMPLOYEE record and all records in the associated EMPLOYEE-EXPERTISE set. The first command retrieves EMPLOYEE 119. Subsequent OBTAIN WITHIN SET statements retrieve the associated EXPERTISE records and establish currency on EXPERTISE 03. The FIND CURRENT statement is used to reestablish the proper position before retrieving EMPLOYEE 48. If FIND CURRENT EMPLOYEE is not specified, an attempt to retrieve the next EMPLOYEE record in the area would return EMPLOYEE 23.
After completion of the FIND/OBTAIN WITHIN SET/AREA function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
0301 |
The area in which the named record participates has not been readied. |
|
0303 |
Invalid currency for a record to be retrieved on a FIND. This can only occur when a run unit is sharing a transaction with other database sessions. The 03 minor status is returned if the run unit tries to find a record using a currency that has been invalidated because of changes made by another database session that is sharing the same transaction. |
|
0306 |
A successful FIND/OBTAIN CALC has not yet been executed (applies to the DUPLICATE option only). |
|
0307 |
The end of the set or area has been reached, or the set is empty. |
|
0308 |
The named record is not in the subschema. The program probably invoked the wrong subschema. |
|
0310 |
The subschema specifies an access restriction that prohibits retrieval of the named record. |
|
0318 |
The record has not been bound. |
|
0326 |
Either the record or SPF index entry cannot be found or no more duplicates exist for the named record. |
|
0331 |
The retrieval statement format conflicts with the record's location mode. |
|
0332 |
The value of the CALC data item in program variable storage does not equal the value of the CALC data item in current record (applies to the DUPLICATE option only). |
|
0364 |
The CALC control element has not been described correctly either in the program or in the subschema. |
|
0370 |
A database file will not open properly. |
If the FIND/OBTAIN statement includes an explicit KEEP: 03 is the major code returned if an error occurs during FIND processing, 06 if the error occurs during KEEP processing.
The FINISH statement commits changes made to the database through an individual run unit or through all database sessions associated with a task. A task-level finish also commits all changes made in conjunction with scratch, queue, and print activity.
If the finish applies to an individual run unit and the run unit is sharing its transaction with another database session, the run unit's changes may not be committed at the time the FINISH statement is executed.
Note: For more information about the impact of transaction sharing, see the CA IDMS Navigational DML Programming Guide.
Run units (and SQL sessions) impacted by the FINISH statement end, and their access to the database is terminated.
The FINISH statement is used in both the navigational and logical record facility environments. The FINISH TASK statement is also used in an SQL programming environment.
Following the successful execution of a FINISH request, all currencies are set to null; the issuing program or task cannot perform database access through an impacted run unit without executing another BIND/READY sequence.
►►─── FINISH ─┬────────┬─ . ──────────────────────────────────────────────────►◄
└─ TASK ─┘
Commits the changes made by all scratch, queue, and print activity and all top-level run units associated with the current task and terminates those run units. Its impact on SQL sessions associated with the task depends on whether those sessions are suspended and whether their transactions are eligible to be shared.
More information:
For more information about the impact of a FINISH TASK statement on SQL sessions, see the SQL Programming Guide.
For more information about run units and the impact of FINISH TASK, see the Navigational DML Programming Guide.
The following statement commits changes made by the run unit through which it is issued and terminates that run unit:
FINISH.
After completion of the FINISH function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
5031 |
The specified request is invalid; the program may contain a logic error |
|
5097 |
An error was encountered processing a syncpoint request; check the log for details. |
The FREE STORAGE statement illustrates a request to release all or a part of a variable storage area. The storage to be released must have been acquired by means of a GET STORAGE request in the issuing task or by another task running on the same terminal as the issuing task. A partial release is valid only for user storage; shared storage must be freed in its entirety.
►►─── FREE STORAGE ───────────────────────────────────────────────────────────►
►─┬─ STGID storage-id ────────────────────────────────────────────────┬─ . ──►◄
└─ FOR 01-level-storage-data-loc ─┬───────────────────────────────┬─┘
└─ FROM start-free-storage-loc ─┘
Specifies variable storage area to be released.
Either the symbolic name of a user-defined field that contains the ID or the ID itself enclosed in quotation marks.
Specifies the LINKAGE SECTION entry of the storage area to be released.
Releases storage from the specified location to the end of the storage area.
The symbolic name of a user-defined field that contains the starting point of the storage area to be released.
The following example illustrates a request to release the storage area identified by 09PA:
FREE STORAGE STGID '09PA'.
After completion of the FREE STORAGE function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
3213 |
The requested storage ID cannot be found |
|
3232 |
The derived length of the variable storage area is zero or negative |
|
3234 |
The request cannot be serviced because the variable storage area is not an 01-level entry in the LINKAGE SECTION |
The GET statement transfers the contents of a specified record occurrence from the record buffer into program variable storage. Elements in the specified record are moved to their respective locations in variable storage according to the subschema view of the record. The transferred elements will appear in storage at the location to which the record has been bound (for further details, see BIND RECORD).
The GET statement operates only on the record that is current of run unit. Following successful execution of a GET statement, the accessed record is current of run unit, its record type, its area, and all sets in which it participates as member or owner.
►►─── GET ─┬───────────────┬─ . ──────────────────────────────────────────────►◄
└─ record-name ─┘
Specifies that the current of run unit must be an occurrence of the named record type.
The following statement moves the record that is current of run unit (in this case, the OFFICE record) from the record buffer into program variable storage:
GET OFFICE.
After completion of the GET function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
0503 |
Invalid currency for a record to be retrieved on a GET. This can only occur when a run unit is sharing a transaction with other database sessions. The 03 minor status is returned if the run unit tries to get a record using a currency that has been invalidated because of changes made by another database session that is sharing the same transaction. |
|
0506 |
Currency has not been established. |
|
0508 |
The named record is not in the subschema. The program has probably invoked the wrong subschema. |
|
0510 |
The subschema specifies an access restriction that prohibits retrieval of the named record. |
|
0513 |
A current record of run unit either has not been established or has been nullified by a previous ERASE statement. |
|
0518 |
The record has not been bound. |
|
0520 |
The current record is not the same type as the named record. |
|
0526 |
The requested record has been erased. |
|
0555 |
An invalid length has been returned for a variable-length record. |
The GET QUEUE statement retrieves a queue record and places it in a storage area associated with the issuing program. If the queue record is larger than the designated storage area, the record is truncated. The retrieved record is automatically deleted from the queue unless the GET QUEUE statement explicitly requests to keep the record in the queue.
►►─── GET QUEUE ─┬───────────────┬─┬─────────────────────────────────┬────────►
└─ ID queue-id ─┘ └─┬─ NEXT ◄ ────────────────────┬─┘
├─ FIRST ─────────────────────┤
├─ LAST ──────────────────────┤
├─ PRIOR ─────────────────────┤
├─ SEQUENCE number ───────────┤
└─ RECORD ID queue-record-id ─┘
►─┬────────────┬─┬──────────┬─┬────────────┬─────────────────────────────────►
├─ DELETE ◄ ─┤ ├─ LOCK ◄ ─┤ ├─ WAIT ─────┤
└─ KEEP ─────┘ └─ NOLOCK ─┘ └─ NOWAIT ◄ ─┘
►─── INTO return-queue-data-location ─┬─ TO end-queue-data-location ───────┬─►
└─ MAX LENGTH queue-data-max-length ─┘
►─┬───────────────────────────────────────────────┬─ . ──────────────────────►◄
└─ RETURN LENGTH INTO queue-data-actual-length ─┘
Specifies the queue associated with the record to be retrieved.
Either the symbolic name of a user-defined field that contains the ID or the ID itself enclosed in quotation marks. If the queue ID is not specified, a null ID of 16 blanks is assumed.
Retrieves the next record in the queue.
This is the default.
If currency has not been established, NEXT is equivalent to FIRST.
Retrieves the first record in the queue.
Retrieves the last record in the queue.
Retrieves the prior record in the queue. If currency has not been established, PRIOR is equivalent to LAST.
Retrieves the specified queue record.
Either the symbolic name of a user-defined field that contains the sequence number of the record or the sequence number itself expressed as a numeric constant.
Retrieves the specified record.
The symbolic name of the PIC S9(8) COMP (fullword) field that contains the queue record ID returned by the PUT QUEUE function.
Deletes the record from the queue.
This is the default.
If DELETE is specified and the record has been truncated, the truncated data is lost.
Keeps the record in the queue.
These parameters have been non-functional since CA IDMS Release 12.0. They are included as parameters for release compatability. Queue record locking is performed as part of the standard database locking routines since CA IDMS Release 12.0.
Suspends task execution until the requested queue exists.
Continues task execution in the event of a nonexistent queue.
This is the default.
An ERROR-STATUS value of 4405 (DC-REC-NOT-FOUND) indicates that the requested queue record cannot be found.
Indicates the WORKING-STORAGE SECTION or LINKAGE SECTION entry of the data area reserved for the requested queue record.
The symbolic name of a user-defined field.
Indicates the end of the WORKING-STORAGE SECTION or LINKAGE SECTION entry reserved for the requested queue record.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the requested queue record.
Explicitly defines the length of the data area reserved for the requested queue record.
Either the symbolic name of the user-defined field that contains the length of the queue records data or the length itself expressed as a numeric constant.
Specifies the location to which CA IDMS is to return the actual length of the retrieved queue record.
The symbolic name of a user-defined four-byte field. If the record has been truncated, the value returned to this field is the actual length of the queue record before truncation.
The following example illustrates a request to retrieve the first record in the RES-Q queue, return it to the PEND-RES field, and keep the record in the queue:
GET QUEUE ID 'RES-Q' FIRST KEEP INTO PEND-RES MAX LENGTH 125.
After completion of the GET QUEUE function, the ERROR-STATUS field of the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
4404 |
The requested queue header record cannot be found. |
|
4405 |
The requested queue record cannot be found. |
|
4407 |
A database error occurred during queue processing. A common cause is a DBKEY deadlock. For a PUT QUEUE operation, this code can also mean that the queue upper limit has been reached. If a database error has occurred, there are usually be other messages in the CA-IDMS/DC/UCF log indicating a problem encountered in RHDCRUAL, the internal Run Unit Manager. If a deadlock has occurred, messages DC001000 and DC001002 are also produced. |
|
4419 |
The program storage area specified for return of the queue record is too small; the returned record has been truncated as appropriate to fit the available space. In a DC-BATCH environment, a possible cause is that the size of the queue record exceeds the value specified in the MAX LENGTH parameter of the BIND TASK statement. In a DC-BATCH environment, a possible cause is that the size of the record read by a GET QUEUE statement exceeds the value specified in the max length parameter of the BIND TASK statement. This can also happen if the record size specified in the GET QUEUE statement is large enough for the queue record, but the maximum specified in the BIND TASK statement is too small. The record size is always truncated to the maximum length determined in the BIND TASK statement. |
|
4431 |
The parameter list is invalid. In DC-BATCH, this code signifies that the specified record length has exceeded the maximum length based on the packet size. |
|
4432 |
The derived length of the queue record data area is negative. |
The GET SCRATCH statement obtains a scratch record and places it in a storage area associated with the issuing program. The storage area must already be allocated to the requesting task; no implicit GET STORAGE function is performed during the GET SCRATCH operation. If the scratch record is larger than the designated storage area, data is truncated.
►►─── GET SCRATCH ─┬───────────────────────────┬──────────────────────────────►
└─ AREA ID scratch-area-id ─┘
►─┬───────────────────────────────┬─┬────────────┬───────────────────────────►
├─ NEXT ◄ ──────────────────────┤ ├─ DELETE ◄ ─┤
├─ FIRST ───────────────────────┤ └─ KEEP ─────┘
├─ LAST ────────────────────────┤
├─ PRIOR ───────────────────────┤
├─ CURRENT ─────────────────────┤
└─ RECORD ID scratch-record-id ─┘
►─── INTO return-scratch-data-loc ─┬─ TO end-scratch-data-loc ────────────┬──►
└─ MAX LENGTH scratch-data-max-length ─┘
►─┬─────────────────────────────────────────────────┬─ . ────────────────────►◄
└─ RETURN LENGTH into scratch-data-actual-length ─┘
Identifies the scratch area associated with the record being retrieved. If you do not specify an area ID, an area ID of eight blanks is assumed.
Either the symbolic name of a user-defined field that contains the scratch area ID or the ID itself enclosed in quotation marks.
Retrieves the next record in the scratch area.
This is the default.
Retrieves the first record in the scratch area.
Retrieves the last record in the scratch area.
Retrieves the prior record in the scratch area.
Retrieves the current record in the scratch area; the current record is the record most recently referenced by another scratch function.
Retrieves the specified scratch record.
The symbolic name of a user-defined PIC S9(8) COMP SYNC (fullword) field that contains the four-byte scratch record ID.
Deletes the record from the scratch area.
This is the default.
If DELETE is specified and the record has been truncated, the truncated data is lost. To maintain currency following a DELETE request, CA IDMS saves the next and prior currencies of the scratch area.
Keeps the record in the scratch area.
Specifies the WORKING-STORAGE SECTION or LINKAGE SECTION entry of the data area to which CA IDMS is to return the scratch record.
The symbolic name of a user-defined field.
Indicates the end of the data area to which CA IDMS will return the scratch record.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the scratch record.
Specifies the length in bytes of the data area associated with the requested scratch record.
Either the symbolic name of a WORKING-STORAGE SECTION or LINKAGE SECTION field that contains the length or the length itself expressed as a numeric constant.
Specifies the WORKING-STORAGE SECTION or LINKAGE SECTION entry to which CA IDMS will return the actual length of the requested scratch record.
The symbolic name of the entry. If the record has been truncated, scratch-data-actual-length will contain the length of the full, untruncated scratch record.
The following statement illustrates a request to return the contents of the current record in the scratch area to the variable-storage area defined by WORK-PROC-AREA and END-WORK-PROC-AREA:
GET SCRATCH CURRENT INTO WORK-PROC-AREA TO END-WORK-PROC-AREA.
After completion of the GET SCRATCH function, the ERROR-STATUS field of the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
4303 |
The requested scratch area ID cannot be found |
|
4305 |
The requested scratch record ID cannot be found |
|
4307 |
An I/O error has occurred during processing |
|
4319 |
The program storage area specified for return of the scratch record is too small; the returned record has been truncated to fit the available space |
|
4331 |
The parameter list is invalid |
|
4332 |
The derived length of the scratch record is negative |
The GET STORAGE statement is used either to acquire variable storage from a DC system storage pool or to obtain the address of a previously acquired storage area. Once acquired, the storage is available for use:
Storage availability is governed by GET STORAGE parameter specifications.
►►─── GET STORAGE FOR 01-level-storage-data-location ─────────────────────────►
►─┬────────────────────────────────┬─────────────────────────────────────────►
└─ TO end-storage-data-location ─┘
►─┬──────────────────────────────┬───────────────────────────────────────────►
└─ LENGTH storage-data-length ─┘
►─┬─────────────────────────────────────────┬────────────────────────────────►
└─ POINTER storage-data-location-pointer ─┘
►─┬──────────┬─┬────────┬─┬──────────┬─┬──────────┬──────────────────────────►
├─ WAIT ───┤ └─ KEEP ─┘ ├─ LONG ◄ ─┤ ├─ USER ◄ ─┤
└─ NOWAIT ─┘ └─ SHORT ──┘ └─ SHARED ─┘
►─┬────────────────────┬─┬──────────────────────────────┬────────────────────►
└─ STGID storage-id ─┘ └─ VALUE IS ─┬─ LOW-VALUE ─────┤
├─ HIGH-VALUE ────┤
└─ initial-value ─┘
►─┬────────────────────────────┬─ . ─────────────────────────────────────────►◄
└─ LOCATION is ──┬─────────┬─┘
├─ ANY ◄ ─┤
└─ BELOW ─┘
Specifies the LINKAGE SECTION entry of the storage area to be acquired.
The name of the 01-level entry used to acquire the storage area.
Specifies the end of the storage area. This parameter is required when the precompiler execution option COBOL=1 is specified. It is accepted but not required if COBOL=2 is specified. See
Note: For more information about the COBOL= option, see Passing Parameters to the Precompiler.
The symbolic name of a user-defined dummy byte field. It is specified as a subordinate item within the 01-level record area following the last real data field.
Note: CA IDMS does not support the use of an OCCURS DEPENDING ON clause within 01-level-storage-data-location.
Specifies the length of the storage location (COBOL 85 only).
The symbolic name of a user-defined field that contains the length of the storage location.
Specifies a pointer that is to receive the address of the storage location (COBOL 85 only).
The symbolic name of a user-defined field that contains a pointer to the address of the storage location.
Specifies that the issuing task will wait until sufficient storage is available in a storage pool.
This is the default.
Specifies that the issuing task will not wait for storage to become available if an insufficient storage condition exists. If NOWAIT is specified, the program should check the ERROR-STATUS field in the IDMS-DC communications block to determine if the GET STORAGE request has been completed. If the ERROR-STATUS value is 3202 (DC-NO-STORAGE), the program should perform alternative processing before reissuing the GET STORAGE request.
Optionally specifies whether the storage area will be used by subsequent tasks executing on the same logical terminal. When KEEP is specified, the storage area can be accessed by subsequent tasks; otherwise the storage area cannot be accessed by subsequent tasks. For a more detailed discussion of the KEEP parameter, refer to CA IDMS Navigational DML Programming Guide.
Allocates storage from the bottom of the storage pool.
This is the default.
You should specify LONG when allocating kept storage to be held across pseudo-converses.
An incorrect LONG/SHORT specification will not affect normal program execution; however, it may affect the overall performance of the DC system.
Allocates storage from the top of the storage pool. You should specify SHORT when allocating small pieces of storage for a short duration.
An incorrect LONG/SHORT specification will not affect normal program execution; however, it may affect the overall performance of the DC system.
Specifies that only the issuing task can access the storage area or, if KEEP is specified, only subsequent tasks executing on the same terminal.
This is the default.
Note: During system execution, a program defined at sysgen with the NOPROTECT option can access any storage area within the system, including an area associated exclusively with another task. Thus, the USER attribute may not protect the storage area being acquired. However, storage areas can be protected on a system-wide or program-by-program basis during system generation and by the modes specified when storage is allocated.
Specifies that any task in the system can access and modify the acquired storage. Each task must establish addressability to the storage area by explicitly issuing a GET STORAGE request.
Specifies storage area. The STGID parameter must be specified with GET STORAGE requests for either previously allocated storage areas or areas to be reallocated.
Either the symbolic name of a user-defined field that contains the storage ID or the ID itself enclosed in quotation marks.
The specified storage ID must be unique; although multiple variable storage areas (that is, one shared and the others user) can have the same ID, only one such area can be owned by a given task at a time. To access the CA IDMS common work area, specify STGID 'CWA'.
Note: If the STGID parameter specifies the address of an existing storage area, the USER/SHARED parameter must specify the same option as that specified in the GET STORAGE statement that originally allocated the storage area.
Specifies how the storage area is to be initialized.
LOW-VALUE Initializes the storage area to all zeros.
HIGH-VALUE Initializes the storage area to the highest value in the computer collating sequence.
Either the symbolic name of a user-defined field that contains the initial value or the value itself enclosed in quotation marks. All bytes of the acquired storage area are initialized to the same value.
Specifies whether the storage is to be restricted to below the 16-megabyte line or if space above the 16-megabyte line is also eligible.
ANY Specifies that space above the 16-megabyte line is eligible for allocation.
This is the default.
BELOW Specifies that storage must be allocated from below the 16-megabyte line.
The following statement illustrates a request to allocate the shared kept storage area, 09PA, and initialize it to all zeros:
GET STORAGE FOR EMPLMENU-KEPT-STORAGE TO EMPLMENU-KEPT-STORAGE-END NOWAIT KEEP SHORT SHARED STGID '09PA' VALUE IS LOW-VALUE.
After completion of the GET STORAGE function, the ERROR-STATUS field of the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
3201 |
The requested storage cannot be allocated immediately; to wait would cause a deadlock |
|
3202 |
The requested storage cannot be allocated because insufficient space exists in the storage pool |
|
3210 |
The request specified a storage ID that did not previously exist; the required space has been allocated |
|
3231 |
The request specifies an invalid parameter list |
|
3232 |
The requested length is zero or negative |
|
3234 |
The request cannot be serviced because the variable storage area is not an 01-level LINKAGE SECTION variable |
|
3235 |
The request cannot be serviced because the specified 01-level LINKAGE SECTION entry has either been previously allocated or contains an OCCURS DEPENDING ON clause |
The GET TIME statement obtains the time of day and date from the operating system. The system time is returned to the issuing task in either fixed binary, packed decimal, or edited format. The date is returned to the program in packed decimal format.
►►─── GET TIME ─┬─────────────────────────────────┬───────────────────────────►
└─ INTO return-time ─┬─ COMP ◄──┬─┘
├─ COMP-3 ─┤
└─ EDIT ───┘
►─┬─────────────────────────┬─ . ────────────────────────────────────────────►◄
└─ DATE INTO return-date ─┘
Specifies the field to which CA IDMS is to return the time.
The symbolic name of a user-defined field to which the current time will be returned. The following format options apply:
COMP Returns the time as a fixed binary value representing the elapsed time since midnight in ten-thousandths of a second.
This is the default.
If COMP is specified, the field associated with return-time should be a PIC S9(8) COMP SYNC (fullword) field. The COMP option returns the most precise time.
COMP-3 Returns the time as a six-byte packed decimal value in the format 0hhmmssttttc (padded zero, hours, minutes, seconds, ten-thousandths of a second, sign). If COMP-3 is specified, the field associated with return-time should be defined as PIC S9(11) COMP-3.
EDIT Returns the time as an edited character string in the format hh:mm:ss:hh (hours, minutes, seconds, hundredths of a second). If EDIT is specified, return-time should be defined as PIC X(11) DISPLAY.
Specifies the field to which CA IDMS is to return the data obtained from the operating system.
The symbolic name of a user-defined COMP-3 PIC S9(7) field. The date is returned in the Julian format 0yyydddc (padded zero, current year relative to 1900, date, sign). For example, 0099365C would represent December 31, 1999. 0100001C would represent January 1, 2000.
The following statement illustrates a request to return the current time and date to the CURRENT-TIME and CURRENT-DATE fields, respectively:
GET TIME INTO CURRENT-TIME EDIT DATE INTO CURRENT-DATE.
After completion of the GET TIME function, the only possible value in the ERROR-STATUS field of the IDMS-DC communications block is 0000.
The IF statement allows the program to test for the presence of member record occurrences in a set and to determine the membership status of a record occurrence in a specified set; once the set has been evaluated, the IF statement specifies further action based on the outcome of the evaluation. For example, an IF statement might be used to determine whether a set occurrence is empty and, if it is empty, to erase the owner record.
Depending on its format, the IF statement uses set or run-unit currency. The object set occurrence of an IF statement is determined by the owner of the current record of the named set; the object record occurrence is determined by the current of run unit.
Each IF statement contains a conditional phrase and an imperative statement. When an IF is issued, the precompiler first generates a call to the DBMS to execute the conditional phrase. Then, the precompiler generates a COBOL IF statement that tests the results of the call to the DBMS to determine whether the imperative statement is executed. Exercise care when nesting DML IF within COBOL IF statements as logic can be difficult to follow. You may need to code explicit scope terminators.
Note: If AUTOSTATUS is in use (see AUTOSTATUS Protocols), IDMS-STATUS is not performed automatically when an IF statement is issued.
Native VSAM users:.The IF statement is not valid for sets defined with member records that are stored in native VSAM data sets.
►►─┬─ IF set-name is ─┬───────┬─ EMPTY ─┬─ imperative-statement . ────────────►◄
│ └─ NOT ─┘ │
│ │
└─ IF ─┬───────┬─ set-name MEMBER ───┘
└─ NOT ─┘
Specifies the set whose owner should be examined for the presence of member record occurrences.
The specified set must be included in the subschema.
Specifies that the imperative statement be executed if the current occurrence of the named set is empty.
Specifies that the imperative statement be executed if the current occurrence of the named set is not empty.
Specifies that the imperative statement be executed if the current record of the run unit is a member of any occurrence of the specified set.
Specifies that the imperative statement be executed if the current record of the run unit is not a member of any occurrence of the specified set.
Identifies the action to execute if the specified condition is true.
The examples below illustrate the use of the IF statement.
The following statement tests the COVERAGE-CLAIMS set for existing CLAIMS members and, if no occurrences of the CLAIMS record are found (ERROR-STATUS is 0000), moves a message to that effect to location CLAIMS-WS.
IF COVERAGE-CLAIMS IS EMPTY MOVE 'NONE' TO CLAIMS-WS.
If the current occurrence of the COVERAGE-CLAIMS set contains one or more occurrences of the CLAIMS record (ERROR-STATUS is 1601), the MOVE statement is ignored and the next statement in the program is executed.
The following statement verifies that the EMPLOYEE record that is current of run unit is not a member of the current occurrence of the OFFICE-EMPLOYEE set before code is executed to connect the EMPLOYEE record to that set.
IF NOT OFFICE-EMPLOYEE MEMBER PERFORM LINK-SET.
If the EMPLOYEE record is not a member of the OFFICE-EMPLOYEE set (ERROR-STATUS is 1601), the program performs the LINK-SET paragraph. If the EMPLOYEE record is already a member of the OFFICE-EMPLOYEE set (ERROR-STATUS is 0000), the PERFORM statement is ignored and the next statement in the program is executed.
After completion of the IF function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
Either the set is empty or the record that is current of run unit is a member of the set |
|
1601 |
Either the set is not empty or the record that is current of run unit is not a member of the set |
|
1606 |
Currency has not been established for the named set |
|
1608 |
Either an invalid set name has been specified or the current record of run unit is not a member of the named set |
|
1613 |
A current record of run unit either has not been established or has been nullified by a preceding ERASE statement |
The INQUIRE MAP statement is used after a map input request to accomplish one of the following actions related to the input operation:
Each of these actions is discussed on the following pages.
The following rules apply to INQUIRE MAP statements:
Moving Map-related Data
This version of the INQUIRE MAP statement moves one of the following map-related data items into variable storage:
►►─── INQUIRE MAP map-name ───────────────────────────────────────────────────►
►─── MOVE ─┬─ AID TO aid-indicator ─────────────────────┬─ . ────────────────►◄
├─ CURSOR TO cursor-row cursor-column ───────┤
└─ IN LENGTH FOR field-name TO field-length ─┘
Specifies the map for which the inquiry is to be made. The specified map must be included in the program's MAP SECTION.
Move screen-related information to program variable storage.
Return the attention ID to the specified location in variable storage.
The symbolic name of a one-byte user-defined field that will be set to the 3270 AID character received in the last map input request. The table below lists the AID characters associated with each 3270-type control key.
Note: The data dictionary includes a record that defines the AID character values as level-88 items to test for particular keyed input by including a COPY IDMS DC-AID-CONDITION-NAMES statement in the WORKING-STORAGE SECTION.
Returns the cursor address from the last map input function to the specified location in program variable storage.
The symbolic names of user-defined PIC S9(4) COMP fields to which the row and column cursor address will be returned.
Specifies to return the length in bytes of the data in the specified map field.
The name of the map field for which the length is being requested.
Specifies where to return the length of the field.
The symbolic name of a user-defined PIC S9(4) COMP field.
Attention ID (AID) Key Values
|
Key |
AID Character |
Key |
AID Character |
|---|---|---|---|
|
ENTER |
''' (single quote) |
PF14 |
'B' |
|
CLEAR |
'_' (underscore) |
PF15 |
'C' |
|
PF01 |
'1' |
PF16 |
'D' |
|
PF02 |
'2' |
PF17 |
'E' |
|
PF03 |
'3' |
PF18 |
'F' |
|
PF04 |
'4' |
PF19 |
'G' |
|
PF05 |
'5' |
PF20 |
'H' |
|
PF06 |
'6' |
PF21 |
'I' |
|
PF07 |
'7' |
PF22 |
'¢' |
|
PF08 |
'8' |
PF23 |
'.' |
|
PF09 |
'9' |
PF24 |
'<' |
|
PF10 |
':' |
PA01 |
'%' |
|
PF11 |
'#' |
PA02 |
'>' |
|
PF12 |
'@' |
PA03 |
',' |
|
PF13 |
'A' |
|
|
The following figure shows the code copied into the program as a result of the COPY IDMS DC-AID-CONDITION-NAMES specification.
*01 COPY IDMS DC-AID-CONDITION-NAMES.
01 DC-AID-CONDITION-NAMES.
03 DC-AID-IND-V PIC X.
88 ENTER-HIT VALUE QUOTE.
88 CLEAR-HIT VALUE '_'.
88 PF01-HIT VALUE '1'.
88 PF02-HIT VALUE '2'.
88 PF03-HIT VALUE '3'.
88 PF04-HIT VALUE '4'.
88 PF05-HIT VALUE '5'.
88 PF06-HIT VALUE '6'.
88 PF07-HIT VALUE '7'.
88 PF08-HIT VALUE '8'.
88 PF09-HIT VALUE '9'.
88 PF10-HIT VALUE ':'.
88 PF11-HIT VALUE '#'.
88 PF12-HIT VALUE '@'.
88 PF13-HIT VALUE 'A'.
88 PF14-HIT VALUE 'B'.
88 PF15-HIT VALUE 'C'.
88 PF16-HIT VALUE 'D'.
88 PF17-HIT VALUE 'E'.
88 PF18-HIT VALUE 'F'.
88 PF19-HIT VALUE 'G'.
88 PF20-HIT VALUE 'H'.
88 PF21-HIT VALUE 'I'.
88 PF22-HIT VALUE '¢'.
88 PF23-HIT VALUE '.'.
88 PF24-HIT VALUE '<'.
88 PA01-HIT VALUE '%'.
88 PA02-HIT VALUE '>'.
88 PA03-HIT VALUE ','.
88 PEN-ATTN-SPACE-NULL VALUE '='.
88 PEN-ATTN VALUE QUOTE.
The following example illustrates the use of an INQUIRE MAP statement to move the 3270 AID character received in the last map input request to DC-AID-IND-V. If the AID character indicates that PF1 was pressed, the program performs a DC RETURN.
INQUIRE MAP EMPMAPLR
MOVE AID TO DC-AID-IND-V. IF CLEAR-HIT DC RETURN.
Testing for Global Map Input Conditions
This version of the INQUIRE MAP statement tests for one of the following global map input conditions:
►►─── INQUIRE MAP map-name ───────────────────────────────────────────────────►
┌────────────────────────┐
►─── IF INPUT ─┬─ UNFORMATTED ─┬─ THEN ─▼─ imperative-statement ─┴─ . ───────►◄
├─ TRUNCATED ───┤
├─ CHANGED ─────┤
└─ EXTRANEOUS ──┘
The name of the map for which the inquiry is being made. The map must be included in the program's MAP SECTION.
Tests the outcome of the last map input request for conditions relating to the data input to the program.
UNFORMATTED Tests whether the screen had been formatted before the input operation was performed.
TRUNCATED Tests whether any of the map fields were truncated when transferred to variable-storage data fields.
CHANGED Tests whether any of the map fields actually had been mapped to variable-storage data fields when the map input operation was performed.
EXTRANEOUS Tests whether the input data stream contained any data from a field not defined to the map. If this condition is true, the undefined data field is ignored by CA IDMS.
Specifies the action to be taken when the test condition is true.
imperative-statement A COBOL statement, a DML statement, or a nested block of COBOL and/or DML statements.
The following example illustrates an INQUIRE MAP statement that tests to determine if any fields in the EMPMAPLR map have been truncated and, if so, requests CA IDMS to perform the DATA-TRUNC routine:
INQUIRE MAP EMPMAPLR IF INPUT TRUNCATED THEN PERFORM DATA-TRUNC.
Testing for Cursor Position
This version of the INQUIRE MAP statement tests a specified map field for the presence of the cursor.
►►─── INQUIRE MAP map-name ───────────────────────────────────────────────────►
┌────────────────────────┐
►─── IF CURSOR at DFLD field-name THEN ─▼─ imperative-statement ─┴─ . ───────►◄
The name of the map for which the inquiry is being made. The map must be included in the program's MAP SECTION.
Determines whether the cursor was in the named map field during the last map input operation.
field-name Identifies the field within the named map to be tested.
Specifies the action to be taken if the test condition is true.
imperative-statement A COBOL statement, a DML statement, or a nested block of COBOL and/or DML statements.
The following example illustrates an INQUIRE MAP statement that tests for the presence of the cursor in the PASSED-DATA-01 data field and, if so, performs the CHECK-2 routine:
INQUIRE MAP EMPMAPLR
IF CURSOR AT DFLD EMP-LAST-NAME-0415
THEN PERFORM CHECK-2.
Testing for Input Non-zero Status Conditions
This version of the INQUIRE MAP statement tests for the following input conditions relating to specific map fields:
►►─── INQUIRE MAP map-name ───────────────────────────────────────────────────►
►─── IF ─┬─┬─ CURRENT ─────────┬───────────┬─────────────────────────────────►
│ ├─ ALL ─────────────┤ │
│ ├─ NONE ────────────┤ │
│ ├─ ANY ─────────────┤ │
│ ├─ SOME ────────────┤ │
│ └─ ALL BUT CURRENT ─┘ │
│ │
├─┬─ ALL ◄ ───┬─ DFLD field-name ─┤
│ ├─ NONE ────┤ │
│ ├─ ANY ─────┤ │
│ ├─ SOME ────┤ │
│ └─ ALL BUT ─┘ │
│ │
└─ DFLD field-name ───────────────┘
►─┬─ DATA is ─┬─ YES ───────┬─┬──────────────────────────────────────────────►
│ ├─ NO ────────┤ │
│ ├─ ERASE ─────┤ │
│ ├─ TRUNCATED ─┤ │
│ ├─ IDENTICAL ─┤ │
│ └─ DIFFERENT ─┘ │
│ │
└─ EDIT is ─┬─ ERROR ───┬───┘
└─ CORRECT ─┘
┌────────────────────────┐
►─── THEN ─▼─ imperative-statement ─┴─ . ────────────────────────────────────►◄
Specifies the map for which the inquiry is being made. The map must be included in the program's MAP SECTION.
Specifies the map fields to which the test applies.
CURRENT Applies the test only to the current field; that is, the map field that was referenced in the last MODIFY MAP or INQUIRE MAP statement issued by the program. If the last MODIFY MAP or INQUIRE MAP statement specified a field list, no currency exists.
ALL Specifies that the test is true if all map fields meet the specified condition.
NONE Specifies that the test is true if none of the map fields meet the specified condition.
ANY Specifies that the test is true if one or more of the map fields meet the specified condition.
SOME Specifies that the test is true if one or more but not all of the map fields meet the specified condition.
ALL BUT CURRENT Specifies that the test is true if all map fields except the current field meet the specified condition.
Specifies the extent to which the condition applies to the map field.
ALL Specifies that the test is true if all of the named map fields meet the specified condition.
NONE Specifies that the test is true if none of the named map fields meet the specified condition.
ANY Specifies that the test is true if one or more of the named map fields meet the specified condition.
SOME Specifies that the test is true if one or more but not all of the named map fields meet the specified condition.
ALL BUT Specifies that the test is true if all map fields except for the named field meet the specified condition.
Specifies the individual map fields to which the test conditions apply.
Multiple DFLD specifications must be separated by at least one blank.
field-name The name of a field within the named map.
Specifies the individual map field(s) to which the test condition applies. The specified field(s) must exist within the named map.
Multiple DFLD specifications must be separated by at least one blank.
Tests the input data in the specified map field(s).
YES Determines if the terminal operator entered data in the specified map field(s).
NO Determines if the terminal operator did not enter data in the specified map field(s).
ERASE Determines if data has been erased from the specified map field(s).
TRUNCATED Determines if data has been truncated in the specified map field(s).
IDENTICAL Tests whether input data is identical to map data currently in program variable storage.
IDENTICAL is true in either of the following cases:
DIFFERENT Tests whether input data is different from map data currently in program variable storage.
DIFFERENT is true if the field's MDT is both:
and
Tests for errors in the named map field(s).
If the EDIT parameter is specified, automatic editing must be enabled for the map and for each of the named map fields.
ERROR Determines if the named map field(s) were found to be in error during automatic editing.
CORRECT Determines if the named map field(s) were found to be correct during automatic editing.
Specifies the action to be taken when the test condition is true.
imperative-statement A single COBOL statement, a DML statement, or a nested block of COBOL and/or DML statements.
The examples below illustrate the use of the INQUIRE MAP statement.
The following example determines if automatic editing has detected erroneous data in any field in the EMPMAPLR map; if so, the program modifies the map temporarily to display the erroneous fields with the bright and blinking attributes:
INQUIRE MAP EMPMAPLR
IF ANY EDIT IS ERROR
THEN MODIFY MAP EMPMAPLR TEMPORARY
FOR ALL ERROR FIELDS
ATTRIBUTES BRIGHT BLINK.
Use an INQUIRE MAP statement to test whether the user has entered an employee ID number:
The sample INQUIRE MAP statement is:
INQUIRE MAP MAP01 IF DFLD EMP-ID-0415 DATA IS IDENTICAL THEN PERFORM EMP-PROMPT-20 ELSE PERFORM EMP-OBTAIN-20.
Use an INQUIRE MAP statement to test whether the user has entered a new department ID or department name. If the user has changed either value (DIFFERENT is true), the program branches to DEPTUP-30:
INQUIRE MAP MAP02
IF ANY DFLD DEPT-ID-0410
DFLD DEPT-NAME-0410 DATA IS DIFFERENT
THEN PERFORM DEPTUP-30.
After completion of the INQUIRE MAP function, the ERROR-STATUS field of the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
4629 |
An invalid parameter has been passed from the program. |
|
4641 |
The test condition has been found to be true. (This condition is tested for automatically by COBOL DML expansion statements.) |
|
4644 |
The referenced map field is not in the specified map; a possible cause is a reference to an invalid map field subscript. |
|
4656 |
The referenced map contains no data fields. |
The KEEP CURRENT statement places an explicit shared or exclusive lock on a record that is current of run unit, record, set, or area. Locks placed on records through the KEEP CURRENT function are maintained for the duration of the database transaction or until explicitly released by means of the COMMIT or FINISH statements.
►►─── KEEP ─┬─────────────┬─ CURRENT ─┬────────────────────┬─ . ──────────────►◄
└─ EXCLUSIVE ─┘ ├─ record-name ──────┤
├─ WITHIN set-name ──┤
└─ WITHIN area-name ─┘
Specifies to place an exclusive lock on the current record of run unit, record, set, or area. If you do not specify EXCLUSIVE, the record receives a shared lock by default.
Specifies to place the lock on the current record of the specified record type.
Specifies to place the lock on the current record of the specified set.
Specifies to place the lock on the current record of the specified area.
The following example places a shared lock on the current EMPLOYEE record occurrence:
KEEP CURRENT EMPLOYEE.
After completion of the KEEP function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
0606 |
Currency has not been established for the named record, set, or area |
|
0608 |
Either the named record or set is not in the subschema or the current record of run unit is not a member of the named set |
|
0610 |
The program's subschema specifies an access restriction that prohibits execution of the KEEP function |
|
0623 |
The named area is not in the subschema |
|
0626 |
The record to be kept has been erased |
|
0629 |
A deadlock has occurred while attempting to set the lock. |
The KEEP LONGTERM statement establishes longterm record locks and/or monitors access to records between tasks. Longterm database locks are used in pseudo-conversational transactions and can be shared or exclusive:
If a record has been locked with a KEEP LONGTERM or KEEP request, restrictions exist on the type of lock that can be placed on that record by other run units. These restrictions are based on existing locks and whether the requesting run unit is executing on the same logical terminal as the run unit that originally placed the lock on the record. The following table illustrates these restrictions.
Keep Longterm Record Lock Options
|
Locks in effect |
Locks allowed for other run units |
Locks disallowed for other run units |
|---|---|---|
|
Shared |
|
|
|
Exclusive |
None |
|
|
Longterm shared |
For all run units:
For run units on the same terminal:
|
For run units on other terminals:
|
|
Longterm exclusive |
For run units on the same terminal:
|
For run units on other terminals:
|
Tasks can monitor database activity associated with a specified record during a pseudo-converse and, if desired, can place a longterm lock on the record being monitored. A subsequent task can then make inquiries about that database activity for the record and take the appropriate action.
CA IDMS maintains information on database activity by using five bit flags, each of which is either turned on (binary 1) or turned off (binary 0). This information is returned to the program as a numeric value. The bit assignments, the corresponding numeric value returned to the program, and a description of the associated database activity follow:
|
Numeric Value |
Bit Assignment |
Description |
|---|---|---|
|
16 |
X'00000010' |
The record was physically deleted |
|
8 |
X'00000008' |
The record was logically deleted |
|
4 |
X'00000004' |
The record's prefix was modified; that is, a set operation (for example, CONNECT or DISCONNECT) occurred involving the record |
|
2 |
X'00000002' |
The record's data was modified |
|
1 |
X'00000001' |
The record was obtained |
To determine the action or combination of actions that has occurred, you can compare the numeric value returned to the program with an appropriate constant. For example:
The maximum possible value is 31, indicating that all the above actions occurred for the specified record.
You may prefer to monitor database activity across a pseudo-converse rather than to set longterm locks. Monitoring does not restrict access to database records, sets, or areas by other run units; however, it does enable a program to test a record for alterations made by other run units. The presence of longterm locks can prevent other run units from accessing locked records for an undesirable amount of time if, during a pseudo-converse, the terminal operator fails to enter a response. If longterm locks are used, you may want to release them at specified intervals.
Note: For more information about the use of timeout intervals, see the CA IDMS System Generation Guide ..
►►─── KEEP LONGTERM ─┬─ ALL ─────────┬────────────────────────────────────────►
└─ longterm-id ─┘
►─┬─ NOTIFY CURRENT ─┬─ record-name ─┬─────────────┬─ . ─────────────────────►◄
│ ├─ set-name ────┤ │
│ └─ area-name ───┘ │
│ │
├─ lock-options ─────────────────────────────────┤
│ │
├─ TEST ─┬─────────────────────────────────────┬─┤
│ └─ RETURN NOTIFICATION into location ─┘ │
│ │
└─ RELEASE ──────────────────────────────────────┘
Expansion of lock-options
►─┬─┬─ SHARE ─────┬─ CURRENT ─┬─ record-name ─┬───────────────────────┬──────►
│ └─ EXCLUSIVE ─┘ ├─ set-name ────┤ │
│ └─ area-name ───┘ │
│ │
└─ UPGRADE ─┬─ SHARE ─────┬─┬─────────────────────────────────────┬─┘
└─ EXCLUSIVE ─┘ └─ RETURN-NOTIFICATION into location ─┘
►─┬──────────────┬───────────────────────────────────────────────────────────►
├─ WAIT ◄ ─────┤
├─ NOWAIT ─────┤
└─ NODEADLOCK ─┘
Used only with the RELEASE parameter, to release all longterm locks kept for the logical terminal associated with the current task.
Either the symbolic name of a user-defined field that contains the longterm ID or the ID itself enclosed in quotation marks. This ID will be used in any subsequent references to the lock, when it is changed or released.
Specifies to monitor database activity associated with the current record. When NOTIFY CURRENT is specified, CA IDMS initializes a preallocated location in the program to contain information on database activity for the specified record.
Monitors database activity associated with the current occurrence of record-name.
Monitors database activity associated with the record current of set-name.
Monitors database activity associated with the record current of area-name.
Specifies to return information on database activity associated with the record identified by longterm-id to a previously allocated location in the program's storage.
The TEST request must specify a longterm lock ID that matches the longterm lock ID specified in a previous KEEP LONGTERM NOTIFY CURRENT request.
The symbolic name of a user-defined PIC S9(8) COMP (fullword) field that contains the WORKING-STORAGE or LINKAGE SECTION entry of the data area to which CA IDMS will return the information.
Releases the longterm lock for the record identified by longterm-id or all record locks (ALL) owned by the logical terminal associated with the current task. RELEASE also releases the information associated with a previous KEEP LONGTERM NOTIFY request.
Applies a longterm shared lock to the specified record.
Applies a longterm exclusive lock to the specified record.
CURRENT record-name Applies the lock to the current occurrence of record-name.
CURRENT set-name Applies the lock to the record current of set-name.
CURRENT area-name Applies the lock to the record current of area-name.
Upgrades a previous KEEP LONGTERM NOTIFY CURRENT request.
SHARE Places a shared longterm lock on the record.
EXCLUSIVE Places an exclusive longterm lock on the record.
Returns information on database activity for the specified record.
return-location The symbolic name of a user-defined PIC S9(8) COMP (fullword) field that contains the WORKING-STORAGE SECTION or LINKAGE SECTION entry of the data area to which CA IDMS will return the information.
Requests the issuing task to wait for an existing lock to be released.
This is the default.
If the wait would cause a deadlock, the task is terminated abnormally.
Requests the issuing task not to wait for an existing lock to be released.
Requests the issuing task to wait for an existing lock to be released, unless to do so would cause a deadlock. If the wait would cause a deadlock, control is returned to the task.
The steps below illustrate the use of the KEEP LONGTERM statement.
KEEP LONGTERM KEEP-ID NOTIFY CURRENT EMPLOYEE.
KEEP LONGTERM KEEP-ID TEST RETURN NOTIFICATION
INTO STAT-VALUE.
KEEP LONGTERM KEEP-ID UPGRADE SHARE.
KEEP LONGTERM ALL RELEASE.
After completion of the KEEP LONGTERM function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
5101 |
The NODEADLOCK option has been specified; however, to wait would cause a deadlock. Control has returned to the issuing task. |
|
5102 |
Unable to obtain storage for the required KEEP LONGTERM control blocks. |
|
5105 |
Either the requested record type cannot be found or currency has not been established. |
|
5113 |
The required area control block was not found in the DMCL. |
|
5121 |
Either the requested longterm ID cannot be found or the KEEP LONGTERM request was issued by a nonterminal task. |
|
5123 |
The specified area cannot be found. |
|
5131 |
The parameter list is invalid. |
|
5147 |
The KEEP LONGTERM area has not been readied. |
|
5148 |
The run unit associated with the KEEP LONGTERM request has not been bound. |
|
5149 |
The NOWAIT option has been specified; however, a wait is required. |
|
5151 |
A lock manager error occurred during the processing of the KEEP LONGTERM request. |
|
5159 |
An error occurred in transferring the KEEP LONGTERM request to IDMSKEEP. |
|
5160 |
The requested KEEP LONGTERM lock ID was already in use with a different page group. |
|
5161 |
The requested KEEP LONGTERM lock ID was already in use with a different dbkey format. |
The LOAD TABLE statement instructs CA IDMS/DC to load a table (module or program) into the program pool and provide access to it through a COBOL LINKAGE SECTION entry.
►►─── LOAD TABLE program ─────────────────────────────────────────────────────►
►─── INTO 01-level-program-location ─┬─ TO end-program-location ────────┬────►
└─ POINTER table-location-pointer ─┘
►─┬──────────────────────┬─┬────────────────────────────┬────────────────────►
└─ DICTNODE nodename ──┘ └─ DICTNAME dictionary-name ─┘
►─┬────────────────────────┬─────────────────────────────────────────────────►
└─ LOADLIB library-name ─┘
►─┬─ WAIT ◄ ─┬─ . ───────────────────────────────────────────────────────────►◄
└─ NOWAIT ─┘
Either the symbolic name of a user-defined field that contains the table or the name itself enclosed in quotation marks.
Specifies the LINKAGE SECTION entry of the 01-level record area that references the loaded table.
The symbolic name of a user-defined field that contains the name of the 01-level LINKAGE SECTION entry used to load the table.
Note: CA IDMS/DC does not support the use of an OCCURS DEPENDING ON clause within 01-level-program-location.
Specifies the end of the LINKAGE SECTION entry of the 01-level record area that references the loaded table.
This parameter is optional under COBOL 85.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the module being loaded. End-program-location is an entry subordinate to the 01-level record.
Specifies a pointer to the address of the table (COBOL 85 only).
The symbolic name of a user-defined field that is to contain the pointer to the address of the table.
Specifies the node that controls the dictionary where the table resides.
Either the symbolic name of a user-defined eight-character field in variable storage or the node name itself enclosed in quotation marks.
Specifies the dictionary where the table resides.
Either the symbolic name of a user-defined eight-character field in variable storage or the dictionary name itself enclosed in quotation marks.
Specifies the load library containing the table.
Either the symbolic name of a user-defined eight-character field in variable storage or the library name itself enclosed in quotation marks.
Requests the issuing task to wait for sufficient storage in the event that program pool storage is not immediately available to meet the requirements of the LOAD TABLE request.
This is the default.
If you specify WAIT and CA IDMS/DC encounters an insufficient storage condition, the issuing task is placed in an inactive state; when the LOAD TABLE function is completed, control returns to the issuing task according to its previously established dispatching priority.
Requests the issuing task not to wait for storage to become available. If you specify NOWAIT, CA IDMS/DC returns a value of 3402 (DC-NO-STORAGE) to the ERROR-STATUS field when an insufficient storage condition exists.
Example
The example below defines the 01-level LINKAGE SECTION entry for use with the LOAD TABLE request for a table built from an Assembler program.
Note: IDD edit and code tables contain special characters andvariable-length fields. In general, such fields are not used in a COBOL program.
The following source code defines the 01-level LINKAGE SECTION entry for use with the LOAD TABLE request:
LINKAGE SECTION.
01 STATE-TABLE.
02 STATES OCCURS 50 TIMES.
03 STATE-ABB PIC X(2).
03 STATE-FULL PIC X(15).
02 END-STATE-TABLE PIC X.
The examples below illustrate the use of the LOAD TABLE statement:
The following statement loads the STATECON table into the 01-level LINKAGE SECTION entry STATE-TABLE:
LOAD TABLE 'STATECON' INTO STATE-TABLE TO END-STATE-TABLE.
The example below defines the 01-level LINKAGE SECTION entry for use with the LOAD TABLE request for an IDD CODE TABLE, defined as follows:
ADD TABLE NAME IS DECODMTH
TABLE DESCRIPTION IS 'MONTH CODE CONVERT'
TYPE IS CODE
SEARCH IS LINEAR
ENCLODE DATA IS ALPHANUMERICPIC 9(4) COMP.
TABLE IS UNSORTED
DUPLICATES ARE NOT ALLOWED
VALUES ARE ( 01 JAN 02 FEB 03 MAR 04 APR
05 MAY 06 JUN 07 JUL 08 AUG
09 SEP 10 OCT 11 NOV 12 DEC ).
The following source code defines the 01-level LINKAGE SECTION entry for use with the LOAD TABLE request:
LINKAGE SECTION.
01 MONTH-TABLE.
02 TABLE-HEADER.
03 HDR-NUM-ENTRIES PIC 9(4) COMP.
02 TABLE-DATA. OCCURS 12 TIMES.
03 DTA-FILLER1 PIC X(2).
03 DTA-MONTH-NUM PIC 9(2).
03 DTA-FILLER2 PIC X.
03 DTA-MONTH-TXT PIC X(3).
02 END-MONTH-TABLE PIC X.
The following statement loads the DECODMTH tables into the 01-level LINKAGE SECTION entry MONTH-TABLE:
PROCEDURE DIVISION USING MONTH-TABLE. LOAD TABLE 'DECODMTH' INTO MONTH-TABLE TO END-MONTH-TABLE.
Note: For BS2000, starting from the COBOL85 compiler V2.2C and higher, each 01-level entry in the LINKAGE SECTION has to be defined in the USING-clause of the PROCEDURE DIVISION.
Note: For BS2000, TABLE definition must be the very last definition in the LINKAGE SECTION.
After completion of the LOAD TABLE function, the ERROR-STATUS field in the CA IDMS/DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
3401 |
The requested module cannot be loaded immediately due to insufficient storage; to wait would cause a deadlock. |
|
3402 |
The requested module cannot be loaded because insufficient storage exists in the program pool. |
|
3407 |
The requested module cannot be loaded because an I/O error has occurred during processing. |
|
3414 |
The requested module cannot be loaded because it has been defined as nonconcurrent and is currently in use. |
|
3415 |
The requested module has been overlaid temporarily in the program pool and cannot be reloaded immediately. |
|
3435 |
The request cannot be serviced because the specified 01-level LINKAGE SECTION entry has either been previously allocated or contains an OCCURS DEPENDING ON clause. |
|
3436 |
Either the requested program is not defined in the program definition table (PDT) or is marked out of service, or null PDEs are not specified or valid in this CA IDMS/DC system. |
The MAP IN statement requests a synchronous transfer of data from map fields on the screen to the corresponding variable-storage data fields. The MAP IN statement can also be used to transfer data from an area in variable storage that contains a 3270-like data stream to map-related variable-storage data fields; this is referred to as a native mode data transfer.
►►─── MAP IN USING map-name ──────────────────────────────────────────────────►
►─┬────────────────────────────────────────────────────────────────────────┬─►
├─ IO ◄ ─────────────────────────────────────────────────────────────────┤
│ │
└─ NOIO DATASTREAM FROM mapped-data-location ─┬─ TO end-data-location ─┬─┘
└─ LENGTH data-length ───┘
►─┬───────────────────────────┬──────────────────────────────────────────────►
└─ INPUT DATA is ─┬─ YES ─┬─┘
└─ NO ──┘
►─┬─────────────────────────┬─┬───────────────────────┬─┬────────────┬─ . ───►◄
├─ DETAIL detail-options ─┤ └─ PAGE is page-number ─┘ └─ MODIFIED ─┘
└─ HEADER ────────────────┘
Expansion of detail-options
►─┬─────────────────────────────────────┬─┬────────────────────────────────┬─► ├─ NEXT ◄ ────────────────────────────┤ └─ RETURNKEY is data-field-name ─┤ ├─ FIRST ─────────────────────────────┤ │ ├─ SEQUENCE NUMBER is seq-field-name ─┘ │ └─ KEY is key ───────────────────────────────────────────────────────────┘
The name of the map to be used for the MAP IN request. It must be a map included in the program's MAP SECTION.
Specifies to transfer data from map fields to variable-storage data fields that are associated with the specified map.
This is the default type of data transfer.
Requests to transfer data from an area in program variable storage to the variable-storage data fields that correspond to the specified map. No terminal I/O is associated with the request.
The symbolic name of a user-defined field that contains the WORKING-STORAGE SECTION or LINKAGE SECTION entry of the data stream to be read by CA IDMS. The length of the data stream is determined by one of the following specifications:
Indicates the end of the WORKING-STORAGE SECTION or LINKAGE SECTION entry that contains the data stream.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the input data stream.
Explicitly defines the length in bytes of the input data stream.
Either the symbolic name of a user-defined field that contains the length of the data stream or the length itself expressed as a numeric constant.
I/O requests only. Specifies whether the contents of all fields of the specified map will be moved to variable-storage data fields, or left unchanged.
This specification applies to all variable-storage data fields unless overridden by an INPUT DATA IS YES/NO clause in a previously issued MODIFY MAP request.
Moves the contents of all fields of the specified map to variable-storage data fields.
Leaves the contents of all variable-storage data fields unchanged.
Pageable maps only. Specifies that the MAP IN operation is to retrieve data from a modified detail occurrence (MDT set on). The contents of all map fields in the detail occurrence are retrieved unless MODIFIED is specified for the MAP IN DETAIL statement; MODIFIED causes only modified fields to be retrieved.
Note: For more information about pageable maps, see the CA IDMS Mapping Facility Guide.
Retrieves the next sequential modified detail occurrence.
This is the default.
An end-of-data condition (DC-NO-MORE-UPD-DETAILS) is returned in either of the following cases:
Retrieves the first available modified detail occurrence.
Retrieves a detail occurrence by sequence number. Detail occurrences are built at run time by the application program and stored in the sequence in which they are created.
A PIC S9(8) COMP (fullword) field.
A detail-not-found condition is returned in either of the following cases:
Specifies the variable field in which CA IDMS stores the four-byte value (if any) associated with the retrieved detail occurrence. If no value is associated with the detail occurrence, the data-field-name is set to zero.
The symbolic name of either a PIC X(4) or PIC S9(8) COMP (fullword) field that contains the key value. Data-field-name does not have to be fullword aligned.
Retrieves a modified detail occurrence based on the value associated with the detail occurrence.
The name of a PIC S9(8) COMP (fullword) field.
Note: A value is associated with a detail occurrence by using the KEY IS parameter in the MAP OUT DETAIL command for that occurrence.
Pageable maps only. Specifies that the MAP IN operation is to retrieve the contents of data fields in the header and footer areas. The contents of all data fields in the header and footer areas are retrieved unless MODIFIED is specified for the MAP IN HEADER statement; MODIFIED causes only modified fields to be retrieved.
Pageable maps only. Specifies the name of a variable field to store the current value of the $PAGE field on mapin.
A PIC S9(8) COMP (fullword) field.
Pageable maps only. Specifies that, within a modified detail occurrence, only modified fields (MDT set on) are to be retrieved in the MAP IN operation.
The examples below illustrate the use of the MAP IN statement.
The following statement illustrates a request to read the EMPMAPLR map. Data values are transferred from map fields on the EMPMAPLR map to the corresponding variable-storage data fields. Subsequent commands can evaluate the input values and perform appropriate processing.
MAP IN USING EMPMAPLR INPUT DATA IS YES.
The following statement illustrates a request to map in the next modified detail occurrence of the EMPMAPPG MAP:
MAP IN USING EMPMAPPG DETAIL NEXT MODIFIED.
After completion of the MAP IN function, the ERROR-STATUS field of the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
4627 |
A permanent I/O error has occurred during processing |
|
4628 |
The dial-up line for the terminal has been disconnected |
|
4631 |
The map request block (MRB) contains an invalid field, indicating a possible error in the program's parameters |
|
4632 |
The derived length of the specified map input data area is zero or negative |
|
4633 |
The map load module named in the MRB cannot be found |
|
4634 |
The LINKAGE SECTION entry specified is not at COBOL 01-Level. |
|
4638 |
The specified 01-level WORKING-STORAGE SECTION or LINKAGE SECTION entry has not been allocated |
|
4639 |
The terminal being used is out of service |
|
4640 |
The NOIO option has been specified but the requested data stream cannot be found |
|
4642 |
The requested map does not support the terminal device being used |
|
4652 |
The specified edit or code table either cannot be found or is invalid for use with the named map |
|
4654 |
A data conversion error has occurred; internal map data does not match the map's data description |
|
4655 |
The user-written edit routine specified for the named map cannot be found |
|
4664 |
The requested node for a header or detail was either not present or not updated |
|
4668 |
No more modified detail occurrences require mapin |
|
4672 |
The scratch record that contains the requested detail could not be accessed (internal error) |
The MAP OUT statement creates or modifies detail occurrences for a pageable map or requests a transfer of data from variable-storage data fields to map fields on the terminal screen. MAP OUT can also be used to transfer data to another area in program variable storage; this is referred to as a native mode data transfer.
►►─── MAP OUT USING map-name ─────────────────────────────────────────────────►
►─┬──────────┬───────────────────────────────────────────────────────────────►
├─ WAIT ◄ ─┤
└─ NOWAIT ─┘
►─┬──────────────────────────────────────────────────────────────────────────►─
├─ IO ◄ ───────────────────────────────────────────────────────────────────
│
└─ NOIO DATASTREAM INTO data-location ─┬─ TO end-data-location ───┬────────
└─ max LENGTH data-length ─┘
─►─────────────────────────────────────────────┬──────────────────────────────►
─────────────────────────────────────────────┤
│
─┬─────────────────────────────────────────┬─┘
└─ RETURN LENGTH into data-actual-length ─┘
►─┬─────────────────────────────────────────────────────────────────────┬────►
└─ OUTPUT ─┬───────────────────────────┬─┬───────────┬─┬────────────┬─┘
└─ DATA is ─┬─ YES ───────┬─┘ ├─ NEWPAGE ─┤ └─ LITERALS ─┘
├─ NO ────────┤ └─ ERASE ───┘
├─ ERASE ─────┤
└─ ATTRIBUTE ─┘
►─┬──────────────────────────────────────────────────────────────┬───────────►
└─ MESSAGE IS message-text ─┬─ TO end-message-data-location ─┬─┘
└─ LENGTH data-length ───────────┘
►─┬──────────────────────────────────────────┬─ . ───────────────────────────►◄
├─ DETAIL ─┬───────────┬─┬──────────────┬──┤
│ ├─ NEW ◄ ───┤ └─ KEY is key ─┘ │
│ └─ CURRENT ─┘ │
│ │
└─ RESUME ─┬─────────────────────────────┬─┘
└─ PAGE is ─┬─ CURRENT ◄ ───┬─┘
├─ NEXT ────────┤
├─ PRIOR ───────┤
├─ FIRST ───────┤
├─ LAST ────────┤
└─ page-number ─┘
The map to be used for the MAP OUT request. The map must be included in the program's MAP SECTION.
Specifies that the data transfer will be synchronous. The issuing task is placed in an inactive state. When the MAP OUT operation is complete, the task resumes processing according to its established dispatching priority.
This is the default.
Specifies that the data transfer will be asynchronous; the task will continue executing. If NOWAIT is specified, the program must issue a CHECK TERMINAL before performing any other I/O operation.
Specifies to transfer data from variable-storage data fields associated with the named map to the terminal device associated with the issuing task.
This is the default.
Specifies to transfer data from variable-storage data fields associated with the named map to another area of program variable storage; no terminal I/O is associated with the request.
The symbolic name of a user-defined field that contains the WORKING-STORAGE SECTION or LINKAGE SECTION entry to which the data is to be transferred.
Indicates the end of the WORKING-STORAGE SECTION or LINKAGE SECTION entry for the output data stream and is specified following the last data-item entry in data-location.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the output data stream.
Defines the maximum length of the output data stream.
Either the symbolic name of the user-defined field that contains the length of the data stream or the length itself expressed as a numeric constant.
Specifies the WORKING-STORAGE SECTION or LINKAGE SECTION entry to which CA IDMS will return the length in bytes of the output data stream.
If the data stream has been truncated, contains the length before truncation.
IO requests only. Specifies screen display options for the data being output.
Specifies whether the variable-storage data fields are to be transmitted to the terminal. This specification applies to all variable-storage data fields unless overridden by an OUTPUT DATA IS YES/NO clause in a previously issued MODIFY MAP request.
Transmits the contents of variable-storage data fields to the corresponding map fields.
Does not transmit the contents of variable-storage data fields to the corresponding map fields. However, if the automatic error handling facility detects an error in any field, CA IDMS will transmit the applicable attribute bytes.
Does not transmit the contents of variable-storage data fields and fills the corresponding map fields with null values.
Transmits only the attribute bytes for variable-storage data fields. Data in the record buffer is not sent to the terminal.
The keywords NEWPAGE and ERASE are synonymous.
Activates the erase-write function; the screen is cleared and both literal and variable fields are transmitted to the map. If NEWPAGE is not specified, any existing screen display is overwritten without first erasing it.
To erase individual map fields, use the OUTPUT DATA IS ERASE option of the MODIFY MAP statement. To erase all screen fields and to activate the erase-write function, the MAP OUT statement must specify OUTPUT DATA IS ERASE NEWPAGE.
Transmits literal fields as well as variable-storage data fields to the terminal. If LITERALS is not specified, literal fields are written to the map only when a MAP OUT request specifies the ERASE option.
IO requests only. Specifies the message to be displayed in the map's message area.
The symbolic name of a WORKING-STORAGE SECTION or LINKAGE SECTION entry that contains the message text.
Specifies the end of the WORKING-STORAGE SECTION or LINKAGE SECTION entry that contains the message text and is specified following the last data item in message-text.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the output data stream.
Defines the length in bytes of the message text.
Either the symbolic name of a user-defined field that contains the length or the length itself expressed as a numeric constant.
Note: The MESSAGE parameter can only be used with MAP OUT DETAIL if the $MESSAGE field is associated with the detail occurrence at map generation.
Note: To reference a message stored in the data dictionary, use the ACCEPT TEXT INTO parameter of the WRITE LOG statement to copy the message into message-text.
Pageable maps only. Specifies that the MAP OUT command is to create or modify a detail occurrence, and optionally associates a numeric key value with the occurrence. For more information about pageable maps, see the Mapping Facility Guide.
Creates a detail occurrence of a pageable map.
This is the default.
Occurrences are displayed in the order in which they are created by the application program.
Modifies the detail occurrence that was referenced by the most recent MAP IN DETAIL or MAP OUT DETAIL statement.
Specifies a value to be associated with the created or modified detail occurrence. The four-byte numeric value is not displayed on the terminal screen.
When the KEY IS parameter is used with the MAP OUT DETAIL CURRENT command, the specified value replaces the value (if any) previously associated with the detail occurrence.
The name of a PIC S9(8) COMP (fullword) field that contains the key of a database record associated with the detail occurrence.
Pageable maps only. Specifies the page of detail occurrences to be mapped out to the terminal.
Redisplays the current page.
This is the default.
If no page has been displayed, the first page of the pageable map is displayed.
Displays the page that follows the current page. If no page follows the current page, the current page is redisplayed.
Displays the page that precedes the current page. If no page precedes the current page, the current page is redisplayed.
Displays the first available page of detail occurrences.
Displays the page of detail occurrences with the highest available page number.
A user field that contains the number of the page to be displayed. A page number is stored in the variable field by a preceding MAP IN PAGE IS page-number statement that names the same numeric variable field.
The examples below illustrate the use of the MAP OUT statement:
The following statement illustrates a request to write all literal and data fields associated with the EMPMAPLR map to the terminal:
MAP OUT USING EMPMAPLR OUTPUT DATA IS YES NEWPAGE MESSAGE IS INITIAL-MESSAGE LENGTH 80.
The following statement maps out the current detail; no terminal I/O is associated with this request if the first page of the pageable map is not yet filled.
MAP OUT USING EMPMAPPG DETAIL KEY IS DETAIL-KEY.
After completion of the MAP OUT function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
4625 |
The output operation has been interrupted; the operator has pressed ATTENTION or BREAK. |
|
4626 |
A logical error (for example, an invalid control character) has been encountered in the output data stream. |
|
4627 |
A permanent I/O error has occurred during processing. |
|
4628 |
The dial-up line for the terminal has been disconnected. |
|
4631 |
The map request block (MRB) contains an invalid field, indicating a possible error in the program's parameters. |
|
4632 |
The derived length of the specified map output data area is zero or negative. |
|
4633 |
The map load module named in the MRB cannot be found. |
|
4634 |
The LINKAGE SECTION entry specified is not at COBOL 01-Level. |
|
4638 |
The WORKING-STORAGE SECTION or LINKAGE SECTION entry specified for return of the output data stream has not been allocated. |
|
4639 |
The terminal being used is out of service. |
|
4640 |
The NOIO option has been specified but the requested data stream cannot be found. |
|
4642 |
The requested map does not support the terminal device being used. |
|
4652 |
The specified edit or code table either cannot be found or is invalid for use with the named map. |
|
4653 |
An error has occurred in a user-written edit routine. |
|
4654 |
A data conversion error has occurred; internal map data does not match the map's data description. |
|
4655 |
The user-written edit routine specified for the named map cannot be found. |
|
4664 |
There is no current detail occurrence to be updated (MAP OUT DETAIL CURRENT only). No action is taken. |
|
4668 |
The amount of storage defined for pageable maps at system generation time is insufficient. No action is taken. This and subsequent MAP OUT DETAIL statements are ignored. |
|
4672 |
No detail occurrence, footer, or header fields exist to be mapped out by a MAPOUT RESUME command. |
|
4676 |
The first screen page has been transmitted to the terminal. |
|
4680 |
A pageable map page has been built but the page has not been displayed. This can happen after you specify STARTPAGE NOAUTODISPLAY. Test for it after each MAP OUT DETAIL statement. |
The MAP OUTIN statement requests an output data transfer (MAP OUT) followed by an input data transfer (MAP IN). MAP OUTIN combines the functions of the MAP OUT and MAP IN requests; however, it cannot be used to perform pageable map functions or native mode data transfers. By definition, the MAP OUTIN request is synchronous; it forces the program to be conversational.
►►─── MAP OUTIN USING map-name ───────────────────────────────────────────────►
►─┬───────────────────────────────────────────────────────────────────────┬──►
└─ OUTPUT ─┬──────────────────────────────────────────────────────────┬─┘
└─ DATA is ─┬─ YES ───────┬─┬─────────────┬─┬────────────┬─┘
├─ NO ────────┤ ├─ NEWPAGE ─┬─┘ └─ LITERALS ─┘
├─ ERASE ─────┤ └─ ERASE ───┘
└─ ATTRIBUTE ─┘
►─┬───────────────────────────┬──────────────────────────────────────────────►
└─ INPUT DATA is ─┬─ YES ─┬─┘
└─ NO ──┘
►─┬──────────────────────────────────────────────────────────────┬─ . ───────►◄
└─ MESSAGE IS message-text ─┬─ TO end-message-data-location ─┬─┘
└─ LENGTH data-length ───────────┘
Specifies the map to be used for the MAP OUTIN request. Must be the name of a map included in the program's MAP SECTION.
Specifies screen display options for the data being output.
Specifies whether variable-storage data fields are to be transmitted to the terminal. This specification applies to all variable-storage data fields unless overridden by an OUTPUT DATA IS YES/NO clause in a previously issued MODIFY MAP request.
Transmits the contents of variable-storage data fields to the corresponding map fields.
Does not transmit the contents of variable-storage data fields to the corresponding map fields. However, if the automatic error handling facility detects an error in any field, CA IDMS will transmit the applicable attribute bytes.
Does not transmit the contents of variable-storage data fields and fills the corresponding map fields with null values.
Transmits only the attribute bytes for variable-storage data fields. Data in the record buffer is not sent to the terminal.
The keywords NEWPAGE and ERASE are synonymous.
Activates the erase-write function; the screen is cleared and both literal and variable fields are transmitted to the map. If NEWPAGE is not specified, any existing screen display is overwritten without first erasing it.
To erase individual map fields, use the OUTPUT DATA IS ERASE option of the MODIFY MAP statement (described later in this chapter). To erase all screen fields and to activate the erase-write function, the MAP OUT statement must specify OUTPUT DATA IS ERASE NEWPAGE.
Specifies to transmit literal fields as well as variable-storage data fields to the terminal. If LITERALS is not specified, literal fields are written to the map only when a MAP OUT request specifies the ERASE option.
Specifies whether the contents of map fields will be moved to variable-storage data fields (YES), or left unchanged (NO).
This specification applies to all variable-storage data fields unless overridden by an INPUT DATA IS YES/NO clause in a previously issued MODIFY MAP request.
Moves the contents of map fields to variable-storage data fields.
Leaves the contents of map fields unchanged.
Specifies the message to be displayed in the map's message area.
The symbolic name of a WORKING-STORAGE SECTION or LINKAGE SECTION entry that contains the message text.
Specifies the end of the WORKING-STORAGE SECTION or LINKAGE SECTION entry that contains the message text and is specified following the last data item in message-text.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the output data stream.
Defines the length in bytes of the message text.
Either the symbolic name of a user-defined field that contains the length or the length itself expressed as a numeric constant.
Note: To reference a message stored in the data dictionary, use the ACCEPT TEXT INTO parameter of the WRITE LOG statement (described later in this chapter) to copy the message into message-text.
The following statement erases the screen, transmits literal and variable map fields (null values), and performs a MAP IN when the operator presses an AID key:
MAP OUTIN USING EMPMAPLR OUTPUT DATA IS ERASE NEWPAGE INPUT DATA IS YES.
After completion of the MAP OUTIN function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
4625 |
The I/O operation has been interrupted; the terminal operator has pressed ATTENTION or BREAK |
|
4626 |
A logical error (for example, an invalid control character) has been encountered in the output data stream |
|
4627 |
A permanent I/O error has occurred during processing |
|
4628 |
The dial-up line for the terminal is disconnected |
|
4631 |
The map request block (MRB) contains an invalid field, indicating a possible error in the program's parameters |
|
4633 |
The map load module named in the MRB cannot be found |
|
4639 |
The terminal being used is out of service |
|
4642 |
The requested map does not support the terminal device being used |
|
4652 |
The specified edit or code table either cannot be found or is invalid for use with the named map |
|
4653 |
An error has occurred in a user-written edit routine |
|
4654 |
A data conversion error has occurred; internal map data does not match the map's data description |
|
4655 |
The user-written edit routine specified for the named map cannot be found |
The MODIFY statement replaces element values of the specified record occurrence in the database with new element values defined in program variable storage.
Before execution of the MODIFY statement, the following conditions must be satisfied:
The following special considerations apply to the modification of CALC- and sort-control elements:
The following special considerations apply to the modification of records in native VSAM data sets:
The specified record must be established as current of run unit.
Following successful execution of the MODIFY statement, the modified record becomes the current record of run unit, its record type, its area, and all sets in which it participates as member or owner.
►►─── MODIFY record-name . ───────────────────────────────────────────────────►◄
The record type to update. The record must be a type included in the subschema. The occurrence of record-name residing in program variable storage will be updated.
The following example illustrates the steps involved in modifying an occurrence of the EMPLOYEE record. Assume that the employee address is to be changed.
MOVE EMP-ID-IN TO EMP-ID-0415. OBTAIN CALC EMPLOYEE.
MOVE NEW-ADDRESS TO EMP-ADDRESS-0415.
MODIFY EMPLOYEE.
After completion of the MODIFY function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
0803 |
Invalid currency for a record to be altered by a MODIFY. This can only occur when a run unit is sharing a transaction with other database sessions. The 03 minor status is returned if the run unit tries to modify a record using a currency that has been invalidated because of changes made by another database session that is sharing the same transaction. |
|
0804 |
The OCCURS DEPENDING ON item is less than zero or greater than the maximum number of occurrences of the control element |
|
0805 |
Modification of the record would violate a duplicates-not-allowed option for a CALC record, a sorted set, or an index set |
|
0806 |
Currency has not been established for the named record |
|
0808 |
The specified record cannot be found; the record name has probably been misspelled |
|
0809 |
The named record's area has not been readied in one of the update usage modes |
|
0810 |
The subschema specifies an access restriction that prohibits modification of the named record |
|
0811 |
There is insufficient space to hold the modified variable-length record occurrence |
|
0813 |
A current record of run unit has not been established or has been nullified by a previous ERASE statement |
|
0818 |
The record has not been bound |
|
0820 |
The current record of run unit is not the same type as the named record |
|
0821 |
An area other than the area of the named record has been readied with an incorrect usage mode |
|
0825 |
No current record of set type has been established |
|
0833 |
At least one sorted set in which the named record participates has not been included in the subschema |
|
0855 |
An invalid length has been defined for a variable length record |
|
0860 |
A record occurrence has been encountered whose type is inconsistent with the set named in the ERROR-SET field of the IDMS communications block; probable causes include: a broken chain and improper database description |
|
0883 |
Either the length of a record in a native VSAM ESDS has been changed or a prime key in a native VSAM KSDS has been modified |
The MODIFY statement changes field values in an existing logical-record occurrence. LRF uses the field values present in the variable storage location reserved for the logical record to update the appropriate database records in the database. You can optionally specify an alternative variable storage location from which the changed field values are to be taken.
►►─── MODIFY logical-record-name ─────────────────────────────────────────────► ►─┬────────────────────────────────────┬─────────────────────────────────────► └─ FROM alt-logical-record-location ─┘ ►─┬────────────────────────────┬─────────────────────────────────────────────► └─ WHERE boolean-expression ─┘ ►─┬───────────────────────────────────────┬─ . ──────────────────────────────►◄ └─ ON path-status imperative-statement ─┘
Updates data field values in the named logical record. Unless the FROM clause is specified (see below), the field values used to update the database are taken from the area in program variable storage reserved for the named logical record. The logical record must be defined in the subschema.
Specifies an alternative variable storage location from which the field values used to perform the requested modification are to be obtained. When modifying a logical record that was retrieved into an alternative location in variable storage, the FROM clause should name the same location specified in the OBTAIN request.
A record location defined in the WORKING-STORAGE SECTION or LINKAGE SECTION.
Specifies the selection criteria to be applied to the named logical record. For details on coding this clause, see Logical-Record Clauses.
The selection criteria to apply.
Specifies the action to be taken depending on the value returned to the LR-STATUS field in the LRC block. For details on coding this clause, see Logical-Record Clauses.
The value of the LR-STATUS field in the LRC block which triggers the specified action.
The action to take.
The following example illustrates the steps taken to modify an occurrence of the EMP-SKILL-LR logical record. Assume that the skill level for employee 120 is to be upgraded from 02 (COMPETENT-0425) to 03 (PROFICIENT-0425).
OBTAIN FIRST EMP-SKILL-LR WHERE EMP-ID-0415 EQ '0120' AND SKILL-ID-0455 EQ '3610' AND COMPETENT-0425.
MOVE '03' TO SKILL-LEVEL-0425.
MODIFY EMP-SKILL-LR.
MODIFY EMP-SKILL-LR
The following figure illustrates the above example by showing three occurrences of the EMP-SKILL-LR logical record.
LRF retrieves the EMP-SKILL-LR logical record where
The bottom EXPERTISE occurrence represents the only data physically modified in the database.
EMPLOYEE EXPERTISE SKILL 120 04 7620 120 03 3710 120 (02) 03 3610
The MODIFY MAP statement modifies options in the map request block (MRB) for a map; modifications can be designated as permanent or temporary. Requested revisions can be field-specific, map-specific, or both; field-specific revisions apply to the map's variable data fields.
Note: The MODIFY MAP statement parameters used to revise predefined map and/or map data field attributes have no defaults. If a MODIFY MAP parameter is not specified, the applicable option remains set to the value specified at map generation or to the value specified in a previously issued MODIFY MAP PERMANENT statement.
►►─── MODIFY MAP map-name ────────────────────────────────────────────────────►◄
►─┬───────────────┬──────────────────────────────────────────────────────────►
├─ PERMANENT ◄ ─┤
└─ TEMPORARY ───┘
►─┬────────────────────────────────────────────┬─────────────────────────────►
└─ CURSOR at ─┬─ cursor-row cursor-column ─┬─┘
└─ DFLD field-name ──────────┘
►─┬──────────────────────────────┬───────────────────────────────────────────►
│ ┌────────────────────┐ │
└─ WCC ─▼─┬─┬─ RESETMDT ─┬─┬─┴─┘
│ └─ NOMDT ────┘ │
│ │
├─┬─ RESETKBD ─┬─┤
│ └─ NOKBD ────┘ │
│ │
├─┬─ ALARM ───┬──┤
│ └─ NOALARM ─┘ │
│ │
├─┬─ STARTPRT ─┬─┤
│ └─ NOPRT ────┘ │
│ │
└─┬─ NLCR ─┬─────┘
├─ 40CR ─┤
├─ 64CR ─┤
└─ 80CR ─┘
►─┬────────────────────────────────────────────────────────┬─────────────────►◄
│ ┌────────────────────────┐ │
└─ FOR field-specifications ──▼─ modification-options ─┴─┘
Expansion of field-specifications
►─┬─ ALL ─┬─ BUT ────┬─ CURRENT ───────────────┬─────────────────────────────►
│ └─ EXCEPT ─┘ │
│ │
├─ ALL ─┬─ CORRECT ─┬─ FIELDS ───────────────┤
│ └─ ERROR ───┘ │
│ ┌───────────────────┐│
└─┬───────────────────┬─▼─ DFLD field-name ─┴┘
├─ ALL ◄ ───────────┤
└─ all ─┬─ BUT ────┬┘
└─ EXCEPT ─┘
Expansion of modification-options
►───┬─┬─ BACKSCAN ───┬─────────────────────────┬─ . ─────────────────────────►
│ └─ NOBACKSCAN ─┘ │
│ │
├─ OUTPUT DATA is ─┬─ YES ───────┬─────────┤
│ ├─ NO ────────┤ │
│ ├─ ERASE ─────┤ │
│ └─ ATTRIBUTE ─┘ │
│ │
├─ INPUT DATA is ─┬─ YES ─┬────────────────┤
│ └─ NO ──┘ │
│ │
├─┬─ RIGHT ─┬─ JUSTIFY ────────────────────┤
│ └─ LEFT ──┘ │
│ │
├─ PAD ─┬─ pad-character ─┬────────────────┤
│ ├─ LOW-VALUE ─────┤ │
│ └─ HIGH-VALUE ────┘ │
│ │
├─ EDIT is ─┬─ ERROR ───┬──────────────────┤
│ └─ CORRECT ─┘ │
│ │
├─┬─ REQUIRED ─┬───────────────────────────┤
│ └─ OPTIONAL ─┘ │
│ │
├─ error message is ─┬─ ACTIVE ─────┬──────┤
│ └─ SUPPRESS ───┘ │
│ │
│ ┌─────────────────────────┐ │
└─ ATTRIBUTES ─▼─┬─ SKIP ──────────────┬─┴─┘
│ │
├─┬─ ALPHAMERIC ─┬────┤
│ └─ NUMERIC ────┘ │
│ │
├─┬─ PROTECTED ───┬───┤
│ └─ UNPROTECTED ─┘ │
│ │
├─┬─ DISPLAY ─┬───────┤
│ ├─ DARK ────┤ │
│ └─ BRIGHT ──┘ │
│ │
├─ DETECT ────────────┤
│ │
├─┬─ MDT ───┬─────────┤
│ └─ NOMDT ─┘ │
│ │
├─┬─ BLINK ───┬───────┤
│ └─ NOBLINK ─┘ │
│ │
├─┬─ REVERSE-VIDEO ─┬─┤
│ └─ NORMAL-VIDEO ──┘ │
│ │
├─┬─ UNDERSCORE ───┬──┤
│ └─ NOUNDERSCORE ─┘ │
│ │
└─┬─ NOCOLOR ───┬─────┘
├─ BLUE ──────┤
├─ RED ───────┤
├─ PINK ──────┤
├─ GREEN ─────┤
├─ TURQUOISE ─┤
├─ YELLOW ────┤
└─ WHITE ─────┘
The name of the map to be modified. It must be a map included in the program's MAP SECTION.
Specifies that modifications will apply to all mapping mode I/O requests issued until the program terminates or until a subsequent MODIFY MAP request overrides the requested revisions.
This is the default.
Specifies that modifications will apply only to the next mapping mode I/O request (that is, MAP IN, MAP OUT, or MAP OUTIN).
Identifies the screen location at which the cursor will be positioned during output operations.
The row on the terminal screen to which the cursor will be moved. Either the symbolic name of the user-defined field that contains the row value or the value itself expressed as a numeric constant. Typically, fields that contains cursor row and column coordinates are level-77 data items defined as PIC S9(4) USAGE COMP (halfword).
The column on the terminal screen to which the cursor will be moved. Either the symbolic name of a user-defined field that contains the column value or the value itself expressed as a numeric constant. Typically, fields that contains cursor row and column coordinates are level-77 data items defined as PIC S9(4) USAGE COMP (halfword).
DFLD Specifies that the cursor will be moved to the first position in the specified field.
The name of a map field.
Specifies the write-control character (WCC) options requested for the output operation.
If a MODIFY MAP request alters any WCC option, unspecified options are reset to the following values:
Specifies that the modified data tags (MDTs) for the map fields will be reset (turned off) automatically when the map is displayed.
Specifies that the modified data tags (MDTs) for the map fields will be not reset (turned off) automatically when the map is displayed. In this case, the associated data is retransmitted to variable-storage data fields during the next MAP IN request.
Specifies that the keyboard will be unlocked automatically when the map is displayed.
Specifies that the keyboard will not be unlocked automatically when the map is displayed.
Specifies that the terminal audible alarm (if installed) will sound automatically when the map is displayed.
Specifies that the terminal audible alarm will not sound automatically when the map is displayed.
3280-type printers only. Specifies that the contents of the terminal buffer will be printed automatically when the data has been transmitted to the terminal.
3280-type printers only. Specifies that the contents of the terminal buffer will not be printed automatically when the data has been transmitted to the terminal.
Specifies that no line formatting will be performed on the printer output. Printing will begin on a new line only if the printer encounters new line (NL) and carriage control (CR) characters.
Specifies that the contents of the 3280-type printer buffer will be printed at 40 characters per line.
Specifies that the contents of the 3280-type printer buffer will be printed at 64 characters per line.
Specifies that the contents of the 3280-type printer buffer will be printed at 80 characters per line.
Specifies the map fields to be modified or excluded from modification.
Modifies all fields except the current field. The current field is the map field that was referenced in the last MODIFY MAP or INQUIRE MAP request issued by the program. However, if that request referenced a list of fields rather than a single map field, no currency exists and all map fields are modified.
BUT and EXCEPT are synonyms and can be used interchangeably.
Modifies all fields found to be correct, during automatic editing or by a user-written edit module.
To specify, ALL CORRECT FIELDS, automatic editing must be enabled for the map.
Modifies all fields found to be in error, during automatic editing or by a user-written edit module.
To specify, ALL ERROR FIELDS, automatic editing must be enabled for the map.
Specifies that all named map fields will receive the requested modifications.
This is the default.
Specifies that all map fields except those named will receive the requested modifications.
BUT and EXCEPT are synonyms and can be used interchangeably.
Specifies the map field(s) to modify or exclude from modification. Multiple DFLD specifications must be separated by at least one blank and must come from the same map record.
The name of the field(s) to modify or exclude from modification.
Field names that are not unique within the program must be qualified with the name of the associated record. Likewise, multiply-occurring fields must be qualified with the appropriate subscripts.
Use the following syntax:
map-data-field-name ─┬─────────────┬──┬────────────────────────┬─
└─ subscript ─┘ └─┬─ IN ─┬─ record-name ─┘
└─ OF ─┘
Specifies to backscan the specified fields to remove trailing blanks before performing a mapout operation. Only characters up to the last nonblank will be sent to the terminal; fields remaining on the screen will contain whatever characters were present before the MAP OUT or MAP OUTIN request was issued. If the MAP OUT or MAP OUTIN request specifies the ERASE option, the contents of all terminal data fields are erased.
Specifies not to backscan the specified fields to remove trailing blanks before performing a mapout operation.
Specifies how to treat the output map fields.
Sets the fields to the value of the corresponding variable-storage data fields.
Leaves the fields unchanged.
Erases the fields.
Transmits only the attribute byte of the fields.
Moves map fields automatically to the corresponding variable-storage data fields during an input operation.
Does not move map fields to the corresponding variable-storage data fields during an input operation.
Right justifies the variable-storage fields on input.
Left justifies the variable-storage fields on input.
Indicates whether variable-storage data fields will be padded on input and, if so, defines the value or character with which the fields are to be padded.
If RIGHT JUSTIFY is specified, fields will be padded on the left; if LEFT JUSTIFY is specified, fields will be padded on the right.
Either the symbolic name of a user-defined PIC X DISPLAY field that contains the pad character or the character itself enclosed in quotation marks.
The fields will be padded with the specified character.
Pads the fields with zeros.
Pads the fields with the highest value in the computer collating sequence.
Explicitly sets the error flag on for the specified map fields.
Automatic editing must be enabled for the map.
The ability to set the error flag enables programs to perform their own editing and validation in addition to that provided by the automatic editing feature.
On a MAPOUT operation, if any field is flagged to be in error, then for all fields (both CORRECT and INCORRECT), only attribute bytes are transmitted; no data is moved from program variable storage to the screen.
Explicitly sets the error flag off for the specified map fields.
Automatic editing must be enabled for the map.
The ability to set the error flag enables programs to perform their own editing and validation in addition to that provided by the automatic editing feature.
On a MAPOUT operation, if any field is flagged to be in error, then for all fields (both CORRECT and INCORRECT), only attribute bytes are transmitted; no data is moved from program variable storage to the screen.
Requires the user to enter data in the specified map fields. An error results on mapin if you specify REQUIRED and the user fails to enter data in a required field.
Automatic editing must be enabled for the map and for the specified map fields.
Does not require the user to enter data in the specified map fields.
Suppresses or enables display of an error message associated with the field.
Enables display of the error message associated with the field.
This is the default.
You typically enable display of a message only after specifying ERROR MESSAGE SUPPRESS for the map in a previous MODIFY MAP PERMANENT statement.
Disables display of the error message associated with the field. When the map is redisplayed because of errors, the message defined for the map field will not be displayed even if the field contains edit errors.
Indicates the 3270- and 3279-type terminal display attributes for the specified map fields.
Multiple attributes must be separated by blanks.
Only the named attributes will be modified in the map's MRB.
Repositions the cursor automatically past the map fields to the next unprotected field. When you specify SKIP, the affected map fields are assigned the NUMERIC and PROTECTED attributes (described below) automatically.
Allows the data input to the map fields by the user to be any character on the 3270 keyboard.
Allows the data input to the map fields by the user to be numeric only. If the terminal does not have the numeric lock option, a specification of NUMERIC is ignored.
Protects the specified map fields from data entry or modification by the user.
Makes the specified map fields available for data entry or modification by the user.
You cannot specify both UNPROTECTED and SKIP.
Displays the specified map fields in normal intensity.
Does not display the specified map fields.
You cannot specify both DARK and DETECT.
Displays the specified map fields in bright intensity.
Fields assigned the BRIGHT attribute are automatically detectable by a light pen.
Makes the specified map fields detectable by a light pen.
Fields assigned the BRIGHT attribute are automatically detectable by a light pen.
Sets the modified data tag automatically for the map fields when they are displayed.
Does not set the modified data tag automatically for the map fields when they are displayed.
3279s only. Displays the specified map fields with blinking characters.
If you specify BLINK, you cannot specify REVERSE-VIDEO or UNDERSCORE.
3279s only. Does not display the specified map fields with blinking characters.
3279s only. Displays the specified map fields in reverse video (background and character colors reversed).
If you specify REVERSE-VIDEO, you cannot specify BLINK or UNDERSCORE.
3279s only. Displays the specified map fields in normal video.
3279s only. Displays the specified map fields with underlined characters. If you specify UNDERSCORE, you cannot specify BLINK or REVERSE-VIDEO.
3279s only. Displays the specified map fields without underlined characters.
3279s only. Specifies the color which the specified map fields will be displayed.
The following examples illustrate the use of the MODIFY MAP statement.
The following statement positions the cursor at EMP-ID-0415 and prohibits the user from entering data in any field except EMP-ID-0415 and DEPT-ID-0410:
MODIFY MAP EMPMAPLR TEMPORARY
CURSOR AT DFLD EMP-ID-0415
FOR ALL BUT DFLD EMP-ID-0415
DFLD DEPT-ID-0410
ATTRIBUTES PROTECTED.
The following statement sets the edit flag on for the TASK-CODE-01 field, thereby overriding automatic editing and error handling for the next MAP IN request:
MODIFY MAP EMPMAPLR TEMPORARY FOR DFLD TASK-CODE-01 EDIT IS ERROR.
Use MODIFY MAP to suppress display of default error messages for fields EMP-ID and DEPT-ID on the current map:
MODIFY MAP EMPMAPLR TEMPORARY FOR DFLD EMP-ID DFLD DEPT-ID ERROR MESSAGE IS SUPPRESS.
Because this MODIFY MAP statement specifies TEMPORARY, error messages for these fields are suppressed for the next mapout only. If PERMANENT (default) were used, the error messages would be suppressed until the program terminated or until the error message specifications were overridden by a subsequent MODIFY MAP statement.
After completion of the MODIFY MAP function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
4629 |
An invalid parameter has been passed from the program |
|
4644 |
The map field is not in the specified map; a possible cause is a reference to an invalid map field subscript |
|
4656 |
The referenced map contains no data fields |
The OBTAIN statement retrieves the named logical record and places it in the variable-storage location reserved for that logical record. The OBTAIN statement can be issued to retrieve a single logical record, or it can be issued in iterative logic to retrieve all logical records that meet criteria specified in the WHERE clause. Additionally, the OBTAIN statement can specify that the retrieved logical record is to be placed into an alternative variable storage location.
►►─── OBTAIN ─┬──────────┬─ logical-record-name ──────────────────────────────►
├─ FIRST ──┤
└─ NEXT ◄ ─┘
►─┬────────────────────────────────────┬─────────────────────────────────────►
└─ INTO alt-logical-record-location ─┘
►─┬────────────────────────────┬─────────────────────────────────────────────►
└─ WHERE boolean-expression ─┘
►─┬───────────────────────────────────────┬─ . ──────────────────────────────►◄
└─ ON path-status imperative-statement ─┘
Retrieves the first occurrence of the logical record. OBTAIN FIRST is typically used to retrieve the first in a series of logical-record occurrences following the iterative retrieval of a different series of logical-record occurrences.
Retrieves a (subsequent) occurrence of the named logical record, in the order specified by the DBA in the path.
This is the default.
OBTAIN NEXT is typically issued in iterative logic to retrieve a series of logical-record occurrences (possibly including the first).
When LRF receives repeated OBTAIN NEXT commands, it replaces field values in program variable storage with new values obtained through repeated access to the appropriate database records, thereby supplying the program with new occurrences of the desired logical record.
If an OBTAIN FIRST statement is followed by an OBTAIN NEXT statement to retrieve a series of occurrences of the same logical record, the OBTAIN statements must direct LRF to the same path. For this reason, you must ensure that the selection criteria specified in the WHERE clause that accompanies the OBTAIN FIRST and OBTAIN NEXT statements describe the same attributes of the desired logical record.
If the program issues an OBTAIN NEXT statement without issuing an OBTAIN FIRST, or if the last path status returned for the path was LR-NOT-FOUND, LRF interprets the OBTAIN NEXT as OBTAIN FIRST. After LR-ERROR or a DBA-defined path status, LRF does not interpret OBTAIN NEXT as OBTAIN FIRST.
The name of a logical record defined in the subschema.
Specifies an alternative location in variable storage into which LRF is to place the retrieved logical record. Any subsequent MODIFY, STORE, or ERASE statements for a logical record placed in alt-logical-record-location should name that area as the one from which LRF is to obtain the data to be used to update the logical record.
A record location defined in the WORKING-STORAGE SECTION or LINKAGE SECTION.
Specifies the selection criteria to be applied to the named logical record. For details on coding this clause, see Logical-Record Clauses.
The selection criteria to apply.
Specifies the action to be taken depending on the value returned to the LR-STATUS field in the LRC block. For details on coding this clause, see Logical-Record Clauses.
The value of the LR-STATUS field in the LRC block which triggers the specified action.
The action to take.
The following example illustrates the use of the OBTAIN NEXT statement to retrieve a series of logical-record occurrences. The program issues the OBTAIN NEXT statement iteratively to retrieve the first and all subsequent occurrences of the EMP-JOB-LR logical record for all employees in the specified department.
GET-AN-ORDER. MOVE DEPT-ID-IN TO DEPT-ID-0410. OBTAIN NEXT EMP-JOB-LR WHERE DEPT-ID-410 EQ DEPT-ID-0410 OF LR. IF LR-STATUS = LR-ERROR PERFORM ERROR-PROCESSING. IF LR-STATUS = LR-NOT-FOUND PERFORM END-PROCESSING. . . . GO TO GET-AN-ORDER.
OBTAIN NEXT EMP-JOB-LR
The following figure illustrates the information retrieved by each OBTAIN NEXT statement. The EMP-JOB-LR logical record consists of DEPARTMENT, OFFICE, EMPLOYEE, and JOB information.
DEPARTMENT EMPLOYEE OFFICE JOB
┌──
ONE OCCURRENCE ──┤ 5100 466 8 SNOWBLOWER
OF EMP-JOB-LR │
│ 5100 467 8 WINDKEEPER
│
│ 5100 334 5 RAINDANCE
│
│ 5100 457 8 STURM UND
└── DRANG
The POST statement alters an event control block (ECB), either by posting it to indicate completion of an event upon which another task is waiting or by clearing it to an unposted status.
►►─── POST ─┬─ EVENT ecb ─────────────────────┬─ . ───────────────────────────►◄
└─ EVENT NAME ecb-id ─┬─────────┬─┘
└─ CLEAR ─┘
Identifies the ECB to be posted.
The symbolic name of a user-defined area that contains three PIC S9(8) COMP SYNC (fullword) fields. Program-allocated ECBs are cleared by moving zeros to ecb.
Specifies the ECB to be posted or cleared.
Either the symbolic name of a user-defined field that contains the ECB ID or the ID itself enclosed in quotation marks.
Clears the specified ECB to an unposted status.
Programs posting and waiting on ECBs are responsible for clearing ECBs before issuing subsequent WAIT requests.
The following example illustrates a request to post the event whose ECB identifier is in the FOUND-ECB field and to clear the ECB to an unposted status:
POST EVENT NAME FOUND-ECB CLEAR.
After completion of the POST function, the only possible value in the ERROR-STATUS field of the IDMS-DC communications block is 0000.
The PUT QUEUE statement stores a queue record in either the DDLDCRUN or the DDLDCQUE area of the data dictionary. CA IDMS assigns an ID to the queue record and places it at the beginning or end of its associated queue.
►►─── PUT QUEUE ─┬───────────────┬────┬──────────┬────────────────────────────►
└─ ID queue-id ─┘ ├─ FIRST ──┤
└─ LAST ◄ ─┘
►─── FROM queue-data-location ─┬─ TO end-queue-data-location ─┬──────────────►
└─ LENGTH queue-data-length ───┘
►─┬────────────────────────────────────────────────┬─────────────────────────►
└─ RETURN RECORD ID INTO return-queue-record-id ─┘
►─┬────────────────────────────────────┬─ . ─────────────────────────────────►◄
└─ RETENTION queue-retention-period ─┘
Directs the queue record to a previously defined queue.
Either the symbolic name of a user-defined field that contains the ID or the ID itself enclosed in quotation marks.
Default: 16 blanks
Places the queue record at the beginning of the queue.
Places the queue record at the end of the queue.
This is the default.
Specifies the WORKING-STORAGE SECTION or LINKAGE SECTION entry associated with the data to be stored in the queue record.
The symbolic name of a user-defined field.
Indicates the end of the WORKING-STORAGE SECTION or LINKAGE SECTION entry that contains the data to be stored in the queue.
The symbolic name of a user-defined dummy byte field or a field that contains a data item not associated with the queue record.
Explicitly defines the length, in bytes, of the area that contains the data to be stored in the queue record.
Either the symbolic name of a user-defined field that contains the length or the length itself expressed as a numeric constant.
Specifies the location in the program to which CA IDMS will return the system assigned ID of the queue record.
The returned ID is used to reference the queue record in subsequent GET QUEUE and DELETE QUEUE statements.
The symbolic name of a user-defined PIC S9(8) COMP (fullword) field.
Specifies the time in days to retain the queue in the data dictionary. At system startup, queues having expired retention periods are automatically deleted. The retention period begins when the first record is stored in the queue.
The specified retention period takes precedence over retention periods associated with previously defined queues. The RETENTION parameter is ignored if the record being allocated is not the first record in the queue.
Either the symbolic name of a user-defined fixed binary field that contains the retention period or the retention period itself expressed as a numeric constant in the range 0 through 255.
A retention period of 255 indicates that the queue is never to be automatically deleted.
Note: If RETENTION is omitted, the default retention period for dynamic queues is taken. For more information on the default retention period for dynamic queues, refer to the System Generation Guide.
The following example illustrates a request to allocate a queue record in the beginning of the RES-Q queue, return the ID of the record to the Q-REC-ID field, and retain the queue for 45 days:
PUT QUEUE ID 'RES-Q' FIRST FROM NEW-RES TO END-NEW-RES RETURN RECORD ID INTO Q-REC-ID RETENTION 45.
After completion of the PUT QUEUE function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
0019 |
In a DC-BATCH environment, the record size exceeds the value specified in the MAX LENGTH parameter of the BIND TASK statement |
|
4407 |
A database error occurred during queue processing. A common cause is a DBKEY deadlock. For a PUT QUEUE operation, this code can also mean that the queue upper limit has been reached. If a database error has occurred, there are usually be other messages in the CA-IDMS/DC/UCF log indicating a problem encountered in RHDCRUAL, the internal Run Unit Manager. If a deadlock has occurred, messages DC001000 and DC001002 are also produced. |
|
4431 |
The parameter list is invalid; under DC-BATCH, this status indicates that the specified record length exceeds the maximum length based on the packet size |
|
4432 |
The derived length of the specified queue record is either zero or negative |
The PUT SCRATCH statement stores or replaces a scratch record in the DDLDCSCR area of the data dictionary. For new records, PUT SCRATCH generates an index entry in a scratch area associated with the issuing task. If the scratch area does not already exist, CA IDMS allocates it dynamically in the storage pool.
►►─── PUT SCRATCH ─┬───────────────────────────┬──────────────────────────────►
└─ AREA ID scratch-area-id ─┘
►─── FROM scratch-data-location ─┬─ TO end-scratch-data-location ─┬──────────►
└─ LENGTH scratch-data-length ───┘
►─┬─────────────────────────────────────────────┬────────────────────────────►
└─ RECORD ID scratch-record-id ─┬───────────┬─┘
└─ REPLACE ─┘
►─┬──────────────────────────────────────────────────┬─ . ───────────────────►◄
└─ RETURN RECORD ID into return-scratch-record-id ─┘
Specifies the scratch area associated with the record being allocated.
If you do not specify an AREA ID, an area ID of eight blanks is assumed.
Either the symbolic name of a user-defined field that contains the ID or the ID itself enclosed in quotation marks.
Specifies the data to be stored in the scratch record.
The symbolic name of a user-defined WORKING-STORAGE SECTION or LINKAGE SECTION entry that contains the data.
Indicates the end of the data area to be stored in the scratch record.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the scratch data being stored.
Defines the length in bytes of the data area.
The symbolic name of a user-defined field that contains the length or the length itself expressed as a numeric constant.
Specifies the ID of the scratch record being stored.
Either the symbolic name of a user-defined PIC S9(8) COMP (fullword) field that contains the ID or the ID itself expressed as a numeric constant.
Specifies that the specified scratch record replaces an existing scratch record. If you specify REPLACE, and the specified scratch record does not exist, the record is stored and the status code is set to 0000.
Returns the automatically assigned ID of a scratch record to the program.
The symbolic name of a user-defined field into which CA IDMS will place the four-byte scratch record ID.
The following statement illustrates a request to replace the scratch record identified by SCR-REC-ID with data in the WORK-PROC-AREA field:
PUT SCRATCH FROM WORK-PROC-AREA LENGTH 125 RECORD ID SCR-REC-ID REPLACE.
After completion of the PUT SCRATCH function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request to add a scratch record has been serviced successfully |
|
4305 |
The requested scratch record ID cannot be found |
|
4307 |
An I/O error has occurred during processing |
|
4317 |
The request to replace a scratch record has been serviced successfully |
|
4322 |
The request to add a scratch record cannot be serviced because the specified scratch record already exists in the scratch area and REPLACE has not been specified |
|
4331 |
The parameter list is invalid. |
|
4332 |
The derived length of the specified scratch record is either zero or negative |
The READ LINE FROM TERMINAL statement requests a synchronous, line-by-line transfer of data from the terminal to the issuing program.
►►─── READ LINE FROM TERMINAL ─┬────────┬────┬──────────────┬─────────────────►
└─ ECHO ─┘ └─ NOBACKPAGE ─┘
►─── INTO input-data-location ─┬─ TO end-input-data-location ───────┬────────►
└─ MAX LENGTH input-data-max-length ─┘
►─┬───────────────────────────────────────────────┬─ . ──────────────────────►◄
└─ RETURN LENGTH into input-data-actual-length ─┘
3270-type devices only. Saves the line of data being input in the current page (as displayed on the screen). If you do not specify ECHO, data entered will not be retained and will not be available for review by the user.
3270-type devices only. Specifies not to save previously input pages in a scratch area. If you specify NOBACKPAGE, the user can view only the current page of data. NOBACKPAGE is valid only with the first input request in a line mode session.
Indicates the WORKING-STORAGE SECTION or LINKAGE SECTION entry reserved for the input data.
The symbolic name of a user-defined field.
Indicates the end of the WORKING-STORAGE SECTION or LINKAGE SECTION reserved for the input data stream.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the data area reserved for the input data stream.
Defines the length in bytes of the input data stream.
If the input data stream is larger than the data area reserved in the WORKING-STORAGE SECTION or LINKAGE SECTION, the data is truncated to fit the available space.
Either the symbolic name of a user-defined field that contains the length of the data area or the length itself expressed as a numeric constant.
Indicates the location to which CA IDMS will return the actual length of the input data stream.
The symbolic name of a user-defined field. If the data stream has been truncated, the field will contain the original length before truncation.
The following examples illustrate the use of the READ LINE FROM TERMINAL statement.
The following statement illustrates a request to read the specified data from a 3270-type device into the specified location in the program and to echo the input data on the screen:
READ LINE FROM TERMINAL ECHO INTO EMPL-DATA TO END-EMPL-DATA.
The following statement illustrates a request to read the specified data into the program but not to save pages associated with the line I/O session:
READ LINE FROM TERMINAL NOBACKPAGE INTO EMPL-DATA MAX LENGTH 8 RETURN LENGTH INTO REC-DATA-LENGTH.
After completion of the READ LINE FROM TERMINAL function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
4707 |
A logical or permanent I/O error has been encountered in the input data stream |
|
4719 |
The input area specified for the return of data is too small; the returned data has been truncated to fit the available space |
|
4731 |
The line request block (LRB) contains an invalid field, indicating a possible error in the program's parameters |
|
4732 |
The derived length of the specified line input area is zero or negative |
|
4738 |
The specified 01-level LINKAGE SECTION entry has not been allocated as required A prior GET STORAGE request must be issued |
|
4743 |
The line I/O session has been canceled; the user has pressed CLEAR (3270s), ATTENTION (2741s), or BREAK (teletypes) |
The READ TERMINAL statement requests a synchronous or asynchronous basic mode data transfer from the terminal to program variable storage.
►►─── READ TERMINAL ──────────────────────────────────────────────────────────►
►─┬──────────┬─┬───────────────────────────────────────────────┬─────────────►
├─ WAIT ◄ ─┤ ├── BUFFER ─────────────────────────────────────┤
└─ NOWAIT ─┘ └── MODIFIED FROM POSITION screen-position ─────┘
►─┬───────────────┬──────────────────────────────────────────────────────────►
└─ GET STORAGE ─┘
►─── INTO input-data-location ─┬─ TO end-input-data-location ───────┬────────►
└─ MAX LENGTH input-data-max-length ─┘
►─┬───────────────────────────────────────────────┬─ . ──────────────────────►◄
└─ RETURN LENGTH into input-data-actual-length ─┘
Specifies that the read operation will be synchronous; the issuing task will automatically relinquish control to CA IDMS and must wait for completion of the read operation before processing can continue.
This is the default.
Specifies that the read operation will be asynchronous; the issuing task will continue executing.
If you specify NOWAIT, the program must issue a CHECK TERMINAL request (described earlier in this chapter) before performing any other I/O operations.
3270-type devices only. Reads all modified fields in the terminal buffer into variable storage without requiring the user to signal completion of data entry.
3270-type devices only. Executes a READ BUFFER command that reads the entire contents of the terminal buffer into variable storage without requiring the user to signal completion of data entry.
Defines the buffer address (screen position) at which the read will start.
Either the symbolic name of a user-defined PIC S9(4) COMP SYNC (halfword) field or the address itself enclosed in quotation marks.
Synchronous requests only. Acquires an input buffer for the data being read into the program; CA IDMS allocates the required storage when the read operation is complete.
Specifies the 01-level WORKING-STORAGE SECTION or LINKAGE SECTION entry of the input data stream.
If you also specify GET STORAGE, the data area reserved for the input data stream must be an unallocated 01-level LINKAGE SECTION entry.
If you do not specify GET STORAGE, the data area must be a WORKING STORAGE or previously allocated LINKAGE SECTION entry.
The symbolic name of a user-defined field.
Indicates the end of the data area reserved for the input data stream.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the data area reserved for the input data stream.
Defines the length, in bytes, of the data area reserved for the input data stream.
If the input data stream is larger than the specified WORKING-STORAGE SECTION or LINKAGE SECTION entry, the data is truncated to fit the available space.
Either the symbolic name of a user-defined field that contains the length of the data area or the length itself expressed as a numeric constant.
Indicates the location to which CA IDMS will return the actual length of the input data stream.
The symbolic name of a user-defined field. If the data stream has been truncated, input-data-actual-length contains the original length before truncation.
The following statement illustrates a basic mode request to read data from the terminal to the specified location in variable storage:
READ TERMINAL WAIT INTO TERM-LINE TO END-TERM-LINE.
After completion of the READ TERMINAL function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
4519 |
The input area specified for the return of data to the issuing program is too small; the returned data has been truncated to fit the available space |
|
4527 |
A permanent I/O error has occurred during processing |
|
4528 |
The dial-up line for the terminal has been disconnected |
|
4531 |
The terminal request block (TRB) contains an invalid field, indicating a possible error in the program's parameters |
|
4532 |
The derived length of the specified input data area is zero or negative |
|
4535 |
Storage for the input buffer cannot be acquired because the specified 01-level LINKAGE SECTION entry has been previously allocated; no I/O has been performed |
|
4537 |
Storage for the input buffer cannot be acquired because the specified entry is defined in the WORKING-STORAGE SECTION rather than in the LINKAGE SECTION; no I/O has been performed |
|
4538 |
The specified 01-level LINKAGE SECTION entry has not been previously allocated and the GET STORAGE option has not been specified; no I/O has been performed |
|
4539 |
The terminal device associated with the issuing task is out of service |
The READY statement prepares a database area for access by DML functions and specifies the usage mode of the area.
The DBA can specify default usage modes in the subschema. Run-units that use such a subschema need not issue any READY statements; the areas are automatically readied in the predefined usage modes. However, if a run-unit issues a READY statement for one area, it must issue READY statements for all areas that it will access unless the FORCE option was specified for the default usage mode. Areas using the default usage mode combined with the FORCE option are automatically readied even if the run-unit already issued READY for other areas.
The specified usage mode can be qualified with a PROTECTED option to prevent concurrent update or an EXCLUSIVE option to prevent concurrent use of areas by other run units executing under the central version. Each area can be readied in its own usage mode. Usage modes can be changed by executing a FINISH statement (see FINISH) then starting a new run unit by issuing a BIND RUN-UNIT statement, the appropriate BIND RECORD statements, and a READY statement specifying the new usage mode.
When the run unit readies database areas, all areas can be readied with a single READY statement or each area to be accessed can be readied individually. All areas affected explicitly or implicitly by the DML statements issued by the run unit must be readied. Other areas included in the subschema need not be readied.
The READY statement can appear anywhere within an application program; however, to avoid runtime deadlock, the best practice is to ready all areas before issuing any other DML statements.
The READY statement is used in both the navigational and the non-navigational environments.
►►─── READY ─┬─────────────┬──────────────────────────────────────────────────►
└─ area-name ─┘
►─┬─────────────────────────────────────────────────────┬─ . ────────────────►◄
└─ USAGE-MODE is ─┬─────────────┬───┬─ RETRIEVAL ◄ ─┬─┘
├─ PROTECTED ─┤ └─ UPDATE ──────┘
└─ EXCLUSIVE ─┘
The name of an area included in the subschema.
By default, if you do not specify an area, READY will open all areas in the subschema.
Specifies the usage mode in which the area will be opened.
Prevents concurrent update of the area by run units executing under the same central version. Once a run unit has readied an area with the PROTECTED option, no other run unit can ready that area in any UPDATE usage mode until the first run unit releases it by means of the FINISH statement (see FINISH). A run unit cannot ready an area with the PROTECTED option if another run unit has readied the area in UPDATE usage mode or with the EXCLUSIVE option.
By default, if you do not specify PROTECTED or EXCLUSIVE, the areas will be opened in shared mode.
Prevents concurrent use of the area by any other run unit executing under the central version. Once a run unit has readied an area with the EXCLUSIVE option, no other run unit can ready that area in any usage mode until the first run unit releases it.
By default, if you do not specify PROTECTED or EXCLUSIVE, the areas will be opened in shared mode.
Opens the area for retrieval only and allows other concurrently executing run units to open the same area in any non-exclusive usage mode.
This is the default.
Opens the area for both retrieval and update and allows other concurrently executing run units to open the same area in any usage mode other than exclusive or protected.
Note: If a READY statement would result in a usage mode conflict for an area, while running under the central version, the run unit issuing the READY is placed in a wait state on the first functional database call.
Note: Modification statements involving areas opened in one of the update usage modes are not valid if they affect sets that include records in an area opened in one of the retrieval usage modes.
The following statement readies all subschema areas in a usage mode of PROTECTED UPDATE:
READY USAGE-MODE IS PROTECTED UPDATE.
After completion of the READY function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
0910 |
The subschema specifies an access restriction that prohibits readying the area in the specified usage mode |
|
0923 |
The named area is not in the subschema |
|
0928 |
The run unit has attempted to ready an area that has been readied previously |
|
0966 |
The area specified is not available for update. If the 0966 status code is ignored, subsequent attempts to access the area will return a 01 or 09 minor code. Probable causes for the return of the status code are as follows:
|
|
0970 |
The database or journal file will not ready properly; a JCL error is the probable cause |
|
0971 |
The page range for the area being readied could not be found in the DMCL |
|
0978 |
A wait for an area would cause a deadlock. It is recommended that all areas be readied either before the first functional call is issued or that all programs ready areas in the same order. |
The RETURN statement retrieves the database key for an indexed record without retrieving the record itself, thus establishing currency in the indexed set. The record's symbolic key is moved into the data fields within the record in program variable storage. The contents of all non-key fields for the record are unpredictable after the execution of the RETURN verb. Optionally, the program can indicate that the symbolic key can be moved into some other specified variable storage location.
Current of index is established by:
The RETURN statement is used in both the navigational and the non-navigational environments.
►►─── RETURN dbkey FROM index-set-name ─┬─ CURRENCY ──────────────┬───────────►
├─ FIRST currency ────────┤
├─ LAST currency ─────────┤
├─ NEXT currency ─────────┤
├─ PRIOR currency ────────┤
└─ USING index-key-value ─┘
►─┬─────────────────────────┬─ . ────────────────────────────────────────────►◄
└─ KEY into symbolic-key ─┘
The symbolic name of a user-defined PIC S9(8) COMP SYNC (fullword) field.
Identifies the indexed set from which the specified database key is to be returned.
The name of the indexed set.
Retrieves the database key for the current index entry.
Retrieves the database key for the first index entry.
Retrieves the database key for the last index entry.
Retrieves the database key for the index entry following current of index. If the current of index is the last entry, status code 1707 (end of index) is returned.
Retrieves the database key for the index entry preceding current of index. If the current of index is the first entry, status code 1707 (end of index) is returned.
Retrieves the database key for the first index entry with the specified symbolic key.
The symbolic key to be used.
If no such entry exists, status code 1726 (index entry not found) is returned.
Saves the symbolic key (CALC, sort, or index) of the specified record.
The name of a user-defined alphanumeric field into which the symbolic key of the specified record will be returned. Symbolic-key must be large enough to contain the largest contiguous or noncontiguous symbolic key.
If the 'KEY into' clause is not specified, the symbolic key will be moved into the corresponding fields in the user record's storage.
The precompiler views an incorrectly formatted RETURN statement as a COBOL RETURN function and does not flag the error. The incorrect RETURN DML statement is passed to the COBOL compiler without expansion into a CALL statement, causing compile-time errors.
The following RETURN statement retrieves the database key for the first index entry in the EMP-LNAME-NDX set and moves the record's symbolic key into the NDX-LNAME-SYM-KEY field.
RETURN INT-INDEX-KEY FROM EMP-LNAME-NDX FIRST CURRENCY KEY INTO NDX-LNAME-SYM-KEY.
After completion of the RETURN function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
1701 |
The area in which the object record or its index owner record participates has not been readied |
|
1707 |
Either the end of the indexed set has been reached or the indexed set is empty |
|
1725 |
Currency has not been established for the specified indexed set |
|
1726 |
The record cannot be found |
The ROLLBACK statement rolls back uncommitted changes made to the database through an individual run unit or through all database sessions associated with a task. A task-level rollback also backs out all uncommitted changes made in conjunction with scratch, queue, and print activity.
Whether the changes are automatically backed out depends on the execution environment:
In these cases, the ROLLBACK statement causes the affected areas to remain locked against subsequent access by other database sessions. They must be manually recovered. If changes cannot be backed out and CONTINUE was specified on the rollback request, a non-zero error status is returned to the application and if the request was for an individual run unit, that run unit is terminated.
Note: For more information about manual recovery, see the CA IDMS Database Administration Guide.
If CONTINUE is not specified, run units (and SQL sessions) impacted by the ROLLBACK statement end, and their access to the database is terminated. If CONTINUE is specified, impacted database sessions remain active after the operation is complete.
The ROLLBACK statement is used in both the navigational and logical record facility environments. The ROLLBACK TASK statement is also used in an SQL programming environment.
Following a ROLLBACK statement, all currencies are set to null. Unless the CONTINUE option is specified, the issuing program or task cannot perform database access through an impacted run unit without executing another BIND/READY sequence.
►►─── ROLLBACK ─┬────────┬──┬────────────┬─ . ────────────────────────────────►◄
└─ TASK ─┘ └─ CONTINUE ─┘
Rolls back the uncommitted changes made by all scratch, queue, and print activity and all top-level run units associated with the current task and terminates those run units. Its impact on SQL sessions associated with the task depends on whether those sessions are suspended and whether their transactions are eligible to be shared.
For more information about the impact of a ROLLBACK TASK statement on SQL sessions, see the SQL Programming Guide.
For more information about run units and the impact of ROLLBACK TASK, see the Navigational DML Programming Guide.
Central version only. Causes the affected run units and SQL sessions to remain active after their changes are backed out. Database access can be resumed without reissuing BIND and READY statements.
Note: The CONTINUE option should not be used in local mode ifdatabase changes have been made.
The following statement reverses the effects of the run unit through which it is issued and terminates the run unit:
ROLLBACK.
After completion of the ROLLBACK function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
1958 |
CONTINUE was specified and database changes could not be backed out. The run unit has been terminated. |
|
5031 |
The specified request is invalid; the program may contain a logic error |
|
5058 |
TASK CONTINUE was specified and database changes could not be backed out. |
|
5097 |
An error was encountered processing a syncpoint request; check the log for details. |
The SEND MESSAGE statement sends a message to another terminal or user or to a group of terminals or users defined as a destination during system generation. The SEND MESSAGE function does not employ the data dictionary message area; instead, CA IDMS places each message in a queue, sending the message to the appropriate terminal only when it is possible to do so without disrupting executing tasks. Typically, CA IDMS sends queued messages to a terminal the next time the ENTER NEXT TASK CODE message is displayed.
►►─── SEND MESSAGE ─┬──────────┬──────────────────────────────────────────────►
├─ ONLY ◄ ─┤
└─ ALWAYS ─┘
►─── TO ─┬─ DEST ID destination-id ─┬────────────────────────────────────────►
├─ USER ID user-id ────────┤
└─ LTERM ID lterm-id ──────┘
►─── FROM message-location ─┬─ TO end-message-location ─┬─ . ────────────────►◄
└─ LENGTH message-length ───┘
Sends the message immediately if the destination, user, or terminal is available, and does not queue the message for subsequent transmission if the destination, user, or terminal is not available.
This is the default.
Note: If ONLY is specified with the DEST ID option (described below) and if some, but not all, of a group of users or terminals in the destination are available, CA IDMS will send the message to those available. The sender will not be aware of any unsuccessful transmissions.
Sends the message immediately if the destination, user, or terminal is available, and queues the message for later transmission if the destination, user, or terminal is not available.
Identifies the recipient of the message as a destination. The specified destination must have been defined during system generation.
Either the symbolic name of a user-defined field that contains the destination ID or the ID itself enclosed in quotation marks.
Identifies the user to receive a message. The specified user can be signed on to any terminal.
Identifies the user to receive the message. The specified user can be signed on to any terminal. User-id is the symbolic name of a 32-byte user-defined field that contains the user-id.
Identifies the logical terminal to receive the message.
Either the symbolic name of a user-defined field that contains the terminal ID or the ID itself enclosed in quotation marks.
Specifies the WORKING-STORAGE SECTION or LINKAGE SECTION entry that contains the text of the message to be sent.
The symbolic name of a user-defined field.
Indicates the end of the WORKING-STORAGE SECTION or LINKAGE SECTION entry that contains the message text.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the message text.
Defines the length in bytes of the message text.
Either the symbolic name of a user-defined field that contains the length or the length itself expressed as a numeric constant.
The following examples illustrate the use of the SEND MESSAGE statement.
The following statement illustrates a request to send the message in the TERM-MESS field to the logical terminal KENNEDYA:
SEND MESSAGE ALWAYS TO LTERM ID 'KENNEDYA' FROM TERM-MESS TO END-TERM-MESS.
The following statement illustrates a request to send the message in the TERM-MESS field to the user field:
MOVE 'KYJOE2' to USER32.
SEND MESSAGE
TO USER ID USER32
FROM TERM-MESS TO END-TERM-MESS.
The following statement illustrates a request to send the message in the TERM-MESS field to the destination ALL:
SEND MESSAGE TO DEST ID 'ALL' FROM TERM-MESS TO END-TERM-MESS.
After completion of the SEND MESSAGE function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
4907 |
An I/O error has occurred during processing. |
|
4921 |
The specified message recipient has not been defined. |
|
4931 |
The parameter list is invalid. |
|
4932 |
The derived length of the specified message data area is zero or negative. |
|
4934 |
The specified variable storage area that contains the message text is in the LINKAGE SECTION but is not an 01-level entry. |
|
4938 |
The specified WORKING-STORAGE SECTION or LINKAGE SECTION entry has not been allocated, as required. A GET STORAGE request must be issued. |
The SET ABEND EXIT (STAE) statement establishes or cancels linkage to an abend routine to which CA IDMS passes control if the issuing task terminates abnormally. Any program within a task can establish an abend exit; however, only one abend exit is in effect at any given time for each task level. If more than one abend exit has been established, CA IDMS recognizes the exit associated with the last STAE request issued.
When a task terminates abnormally (following either a processing error or an ABEND request), abend exits for the program that was executing at the time of the abend and for all higher-level programs will be executed before the task is terminated. The program can prevent CA IDMS from executing abend exits automatically either by coding the EXITS IGNORED clause in an ABEND request or by coding a DC RETURN request in the abend routine.
►►─── SET ABEND EXIT ─┬─ on PROGRAM program ─┬─ . ────────────────────────────►◄
└─ OFF ────────────────┘
Specifies the program to which control is to transfer if the issuing task terminates abnormally.
Either the symbolic name of a user-defined field that contains the program name or the name itself enclosed in quotation marks.
Note: CA IDMS does not check to determine if the specified program name is valid when the STAE request is issued. Rather, if the program is not found or is otherwise unloadable when CA IDMS attempts to execute it, the STAE request will be ignored.
Cancels any previously issued STAE request for the issuing task level.
The following examples illustrate the use of the SET ABEND EXIT statement.
The following statement establishes an abend exit that will execute the program ABENDRTN if the issuing task terminates abnormally:
SET ABEND EXIT ON PROGRAM 'ABENDRTN'.
The following statement cancels all abend exits previously established at the task level of the issuing program:
SET ABEND EXIT OFF.
After completion of the SET ABEND EXIT function, the only possible value in the ERROR-STATUS field of the IDMS-DC communications block is 0000.
The SET TIMER statement defines an event that is to occur after a specified time interval or cancels the effect of a previously issued SET TIMER request. Using the SET TIMER function, a program can:
►►─── SET TIMER ─┬─ WAIT────┬─────────────────────────────────────────────────►
├─ POST ───┤
├─ START ──┤
└─ CANCEL ─┘
►─┬──────────────────────────────────┬───────────────────────────────────────►
└─ INTERVAL time-interval seconds ─┘
►─┬──────────────────┬───────────────────────────────────────────────────────►
└─ EVENT post-ecb ─┘
►─┬───────────────────────────────────────────────┬──────────────────────────►
└─ TASK CODE task-code ─┬─────────────────────┬─┘
└─ PRIORITY priority ─┘
►─┬────────────────────────┬─────────────────────────────────────────────────►
└─ TIMER ID ice-address ─┘
►─┬────────────────────────────────────────────────────────────────┬─ . ─────►◄
└─ DATA FROM task-data-location ─┬─ TO end-task-data-location ─┬─┘
└─ LENGTH task-data-length ───┘
Places the issuing task in a wait state and redispatches the issuing task after the specified time interval elapses. Because WAIT relinquishes control until the time interval has elapsed, a subsequent SET TIMER request cannot be used to cancel this WAIT request.
Posts a user-specified ECB after the specified time interval elapses; the issuing task continues to run. If POST is specified, the EVENT parameter (described below) must also be specified.
Initiates a user-specified task after the specified time interval elapses. If START is specified, the TASK CODE parameter (described below) must also be specified.
Cancels the effect of a previously issued SET TIMER request.
WAIT, POST, START requests only. Specifies the time, in seconds, from the issuance of a SET TIMER request at which the requested event will occur.
Either the symbolic name of a user-defined field that contains the time interval or the interval itself expressed as a numeric constant.
POST requests only. Specifies the ECB to be posted.
The symbolic name of a user-defined area that contains three PIC S9(8) COMP SYNC (fullword) fields.
Note: The POST instruction will only POST an ECB that is within storage owned by the TASK initiating the POST instruction. If the storage is not owned by the same task, it will not be executed.
START requests only. Specifies the task to be initiated.
Either the symbolic name of the user-defined field that contains the task code or the task code itself enclosed in quotation marks.
The specified task code must have been defined to CA IDMS during system generation or at runtime with a DCMT VARY DYNAMIC TASK command.
Specifies a dispatching priority for the task.
Either the symbolic name of a user-defined field that contains the priority or the priority itself expressed as a numeric constant in the range 0 through 240. The new task's priority defaults to the priority defined for that task code.
POST, START, CANCEL requests only. Specifies the address of the interval control element (ICE) associated with the timed event.
The symbolic name of a user-defined PIC S9(8) COMP SYNC (fullword) field. If either POST or START has been specified, ice-address references a field to which CA IDMS will return the ICE address. If CANCEL has been specified, ice-address references the field that contains the ICE address returned by CA IDMS following a SET TIMER POST or SET TIMER START request.
Note: The TIMER ID parameter must be specified with SET TIMER POST and SET TIMER START requests if the program is to issue subsequent SET TIMER CANCEL requests.
START requests only. Identifies the user data to be passed to the new task.
The symbolic name of a user-defined field that identifies the beginning of an area containing the data item(s) to be passed.
Indicates the end of the data area being passed to the new task.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the data area being passed.
Specifies the length in bytes of the data area.
Either the symbolic name of a user-defined WORKING-STORAGE SECTION or LINKAGE SECTION field that contains the length of the data area or the length itself expressed as a numeric constant.
Note: The data passed to the new task consists of two bytes containing the length of the original data followed by the original data itself. This may be accessed by means of a LINKAGE SECTION entry corresponding to the data and a USING clause in the PROCEDURE DIVISION header.
The following examples illustrate the use of the SET TIMER statement.
The following statement illustrates a request to place the issuing task in a wait state and redispatch it after nine seconds have elapsed:
SET TIMER WAIT
INTERVAL 9 SECONDS.
The following statement illustrates a request to post the event PODB after five seconds have elapsed:
SET TIMER POST
INTERVAL 5 SECONDS EVENT PODB TIMER ID TMR-ID.
The following statement illustrates a request to start the SPSG task after five seconds have elapsed and to pass the specified data to that task:
SET TIMER START
INTERVAL 5 SECONDS TASK CODE 'SPSG' TIMER ID TMR-ID DATA FROM PASSGR LENGTH REC-LENGTH.
The following statement illustrates a request to cancel the timed event referenced by TMR-ID:
SET TIMER CANCEL
TIMER ID TMR-ID.
After completion of the SET TIMER function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
3512 |
The specified task code is not known to the DC/UCF system. |
|
3516 |
The interval control element (ICE) specified for a SET TIMER CANCEL request cannot be found |
|
3531 |
Parameter list is invalid. |
|
3532 |
The derived length of the data area is negative |
The SNAP statement requests a memory snap of one or all of the following areas:
The areas requested in the SNAP request are written to the DC system log file, which is defined during system generation as a sequential data set or a data dictionary area.
►►─── SNAP ─┬──────────────────┬─┬──────────┬─────────────────────────────────►
└─ TITLE is title ─┘ ├─ ALL ────┤
├─ SYSTEM ─┤
└─ TASK ───┘
►─────┬───────────────────────────────────────────────────────────┬─ . ──────►◄
│ ┌───────────────────────────────────────────────────────┐ │
└─▼─ FROM begin-snap-location ─┬─ TO end-snap-location ─┬─┴─┘
└─ LENGTH snap-length ───┘
Specifies the title to be printed at the beginning of each page of the snap.
The symbolic name of a user-defined field that contains the title.
A title must contain 134 characters; the first character is reserved for use by CA IDMS, and the second character must be a valid ASA carriage control character (blank, 0, 1, +, or -).
Writes a snap of both task and system areas. Areas associated with the issuing task are formatted separately from the system areas. (Task areas are also included with the system areas but are not itemized by task.)
Writes a snap of system areas.
Writes a snap of task areas.
Writes a snap of the specified memory location.
The symbolic name of a user-defined field indicating the starting location of the area to be snapped.
Indicates the end of the area to be snapped.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the area requested in the snap.
Defines the length in bytes of the area to be included in the snap.
Either the symbolic name of a user-defined field that contains the length of the data area or the length itself expressed as a numeric constant.
Note: If snap-length is greater than 100, some COBOL compilers may produce errors. In this case, either use a symbolic name that contains the length, or use the FROM/TO form of the verb.
The following example illustrates a SNAP statement that requests CA IDMS to write a memory snap of the specified memory location:
SNAP TITLE IS SNAP-TITLE FROM WS-START TO WS-END.
After completion of the SNAP function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
4032 |
The derived length of the specified snap storage area is zero or negative |
The STARTPAGE statement initiates a paging session. It can be followed by any number of DML commands, including MAP IN and MAP OUT commands. The map paging session is terminated by an ENDPAGE command (or by another STARTPAGE command, if one is encountered before an ENDPAGE command).
Note: Only one pageable map can be handled by the statements enclosed by a given STARTPAGE/ENDPAGE pair.
►►─── STARTPAGE session map-name ─┬────────────┬──────────────────────────────►
├─ WAIT ─────┤
├─ NOWAIT ◄ ─┤
└─ RETURN ───┘
►─┬──────────────┬─┬────────────┬─┬─────────────────┬─ . ────────────────────►◄
├─ BACKPAGE ◄ ─┤ ├─ UPDATE ◄ ─┤ ├─ AUTODISPLAY ◄ ─┤
└─ NOBACKPAGE ─┘ └─ BROWSE ───┘ └─ NOAUTODISPLAY ─┘
Specifies the pageable map to be used for the session.
Specifies that runtime mapping automatically handles paging transactions that do not cause data to be updated. Control is passed to the program when the user presses a control key that requests an update or nonpaging operation.
Specifies that runtime mapping automatically handles all paging and update transactions.
This is the default.
Control is passed to the program only when neither an update nor paging request is made when the operator presses a control key.
Specifies that runtime mapping does not handle any terminal transactions in the paging session. Control is passed to the program whenever the operator presses a control key.
Note: Runtime mapping does not update program variable storage unless a MAP IN command is issued. In cases where the operator can update data, it is recommended that WAIT or RETURN be specified for the session so that data can be retrieved as it is updated.
Specifies that the operator can display previous pages of detail occurrences.
This is the default.
Specifies that the operator cannot display any page of detail occurrences with a page number lower than the current page number. Modifications made on a given page of the map must be requested by MAP IN statements in the application program before a MAP OUT RESUME command is issued. The previous page of detail occurrences is deleted from the session scratch record when a new map page is displayed.
Note: NOBACKPAGE cannot be assigned if UPDATE and NOWAIT are specified for the session.
Specifies that the user can modify variable map fields, subject to restrictions specified for the map either at map definition time or by statements in the program.
This is the default.
Specifies that the user can modify only the page and response fields (if any) of the map. The MDTs for variable fields on the map can be set on only according to specifications made either in the map definition or by statements in the program.
Enables automatic display of the pageable map's first page.
This is the default.
Disables automatic display of the pageable map's first page. You manually display the page by using a MAP OUT RESUME statement.
The following statement initiates a paging session in which the operator can page forward and backward within the pageable map but can make no modifications:
STARTPAGE SESSION EMPMAPPG NOWAIT BACKPAGE BROWSE.
Use STARTPAGE to override automatic display for the first page of pageable map EMPMAPPG:
STARTPAGE SESSION EMPMAPPG NOAUTODISPLAY.
After completion of the STARTPAGE function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
4604 |
A paging session was already in progress when this STARTPAGE command was received. An implied ENDPAGE was processed before this STARTPAGE was successfully executed. |
The STORE statement performs the following functions:
Before execution of the STORE statement, the following conditions must be satisfied:
A record is stored in the database based on the location mode specified in the schema definition of the record. The location modes are as follows:
Following successful execution of a STORE statement, the stored record becomes current of run unit, its record type, its area, and all sets in which it participates as owner or automatic member.
►►─── STORE record-name . ────────────────────────────────────────────────────►◄
The name of a record type included in the subschema. The current occurrence of the record type will be moved from variable storage to the database, connected to an occurrence of each set for which it is defined as an automatic member, and established as the owner of a set occurrence for each set in which it is defined as an owner.
The ordering rules for each set govern the insertion point of the specified record in the set.
The following figure illustrates the steps necessary to add a new EMPLOYEE record to the database. Since EMPLOYEE is defined as an automatic member of both the DEPT-EMPLOYEE and OFFICE-EMPLOYEE sets, currency must be established in each of those sets before issuing the STORE. The first two DML statements establish OFFICE 1 and DEPARTMENT 3100 as current of the OFFICE-EMPLOYEE and DEPT-EMPLOYEE sets, respectively. When EMPLOYEE 27 is stored, it is connected automatically to each set.
After completion of the STORE function, the ERROR-STATUS field in the IDMS communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
1201 |
The area in which the named record is to be stored has not been readied |
|
1202 |
The suggested DIRECT-DBKEY value is not within the page range for the named record |
|
1203 |
Invalid currency for a record to be inserted by a STORE. This can only occur when a run unit is sharing a transaction with other database sessions. The 03 minor status is returned if the run unit tries to store a record and a currency in any set in which the record is a owner or member of has been invalidated because of changes made by another database session that is sharing the same transaction. |
|
1204 |
The OCCURS DEPENDING ON item is either less than zero or greater than the maximum number of occurrences of the control element |
|
1205 |
Storage of the record would violate a duplicates-not-allowed option for a CALC record, a sorted set, or an index set |
|
1208 |
The named record is not in the subschema; The program has probably invoked the wrong subschema. |
|
1209 |
The named record's area has not been readied in one of the update usage modes |
|
1210 |
The subschema specifies an access restriction that prohibits storage of the named record |
|
1211 |
The record cannot be stored in the area because of insufficient space |
|
1212 |
The record cannot be stored because no db-key is available; this is a system internal error. |
|
1218 |
The record has not been bound |
|
1221 |
An area other than the area of the named record occurrence has been readied with an incorrect usage mode |
|
1225 |
A set occurrence has not been established for each set in which the named record is to be stored |
|
1233 |
At least one set in which the record participates as an automatic member has not been included in the subschema |
|
1253 |
The subschema definition of an indexed set does not match the indexed set's physical structure in the database |
|
1254 |
Either the prefix length of an SR51 record is less than zero or the data length is less than or equal to zero |
|
1255 |
An invalid length has been defined for a variable length record |
|
1260 |
A record occurrence encountered in the process of connecting automatic sets is inconsistent with the set named in the ERROR-SET field of the IDMS communications block; probable causes include: a broken chain and improper database description. |
|
1261 |
The record cannot be stored because of broken chains in the database |
The STORE statement updates the database with field values for a logical-record occurrence. STORE does not necessarily result in storing new occurrences of all or any of the database records that participate in the logical record; the path selected to service a STORE logical-record request performs whatever database access operations the DBA has specified to service the request. For example, if an existing department gets a new employee, only the new employee information will be stored in the database; the department information need not be stored in the database because it already exists.
LRF uses field values present in the variable storage location reserved for the logical record to make the appropriate updates to the database. You can optionally name an alternative storage location from which the new field values are to be obtained to perform the requested store operation.
►►─── STORE logical-record-name ──────────────────────────────────────────────► ►─┬────────────────────────────────────┬─────────────────────────────────────► └─ FROM alt-logical-record-location ─┘ ►─┬────────────────────────────┬─────────────────────────────────────────────► └─ WHERE boolean-expression ─┘ ►─┬───────────────────────────────────────┬─ . ──────────────────────────────►◄ └─ ON path-status imperative-statement ─┘
The name of a logical record defined in the subschema.
Specifies an alternative variable storage location that contains the field values to be used to make appropriate updates to the database. When storing a logical record that has previously been retrieved into an alternative variable storage location, use the FROM clause to name the same area specified in the OBTAIN request.
A record location defined in the WORKING-STORAGE SECTION or LINKAGE SECTION.
Specifies selection criteria to be applied to the object logical record. For details on coding this clause, see Logical-Record Clauses.
The selection criteria to apply.
Specifies the action to be taken depending on the value returned to the LR-STATUS field in the LRC block. For details on coding this clause, see Logical-Record Clauses.
The value of the LR-STATUS field in the LRC block which triggers the specified action.
imperative-statement The action to take.
The following example illustrates the steps necessary to store a new EMP-INSURANCE-LR for a given employee:
MOVE EMP-ID-IN TO EMP-ID-0415. MOVE INS-PLAN-IN TO INS-PLAN-CODE-0435. MOVE S-DATE-IN TO SELECTION-DATE-0400 MOVE T-DATE-IN TO TERMINATION-DATE-0400 MOVE TYPE-IN TO TYPE-0400 MOVE PLAN-IN TO INS-PLAN-CODE-0400. STORE EMP-INSURANCE-LR.
The following figure illustrates the new occurrence of the EMP-INSURANCE-LR, which consists of EMPLOYEE 149, INS-PLAN 001, and COVERAGE 'D'. The bottom COVERAGE occurrence represents the only data physically added to the database.
EMPLOYEE INS-PLAN COVERAGE
┌──
NEW OCCURRENCE │ 149 002 M
OF EMP-INS-LR ──┤
│ 149 002 F
│
│ 149 001 (D)
└──
The TRANSFER CONTROL statement is used to:
►►─── TRANSFER CONTROL to program ─┬────────────────────┬─────────────────────►
├─┬─ RETURN ─┬───────┤
│ └─ LINK ───┘ │
│ │
└─┬─ NORETURN ─┬─ ◄ ─┘
└─ XCTL ─────┘
►─┬─────────────────────────┬──┬─ . ─┬───────────────────────────────────────►◄
│ ┌─────────────┐ │ └─ ; ─┘
└─ USING ─▼─ parameter ─┴─┘
Either the symbolic name of a user-defined field that contains the program name or the name itself enclosed in quotation marks.
Establishes linkage with the specified program, expecting return of control.
RETURN and LINK are synonyms and can be used interchangeably.
Transfers control to the specified program, not expecting return of control.
This is the default.
NORETURN and XCTL are synonyms and can be used interchangeably.
Passes one or more parameters (data items) to the program receiving control.
The symbolic name of a user-defined field that contains the names of the data items to be passed. Multiple parameter specifications must be separated with a blank.
If the USING clause is specified with the RETURN option, the data items being passed are defined in either the WORKING-STORAGE SECTION or the LINKAGE SECTION of the calling program, and in the LINKAGE SECTION of the linked program.
If the USING clause is specified with the NORETURN option, the data items being passed are defined in the LINKAGE SECTION of both the calling program and the program receiving control. In either case, the program receiving control must have a corresponding USING clause and parameter list as part of its PROCEDURE DIVISION header.
The following examples illustrate the use of the TRANSFER CONTROL statement.
The following statement illustrates a request to transfer control to the program in the PROGRAM-NAME field; the issuing program expects return of control:
TRANSFER CONTROL TO PROGRAM-NAME LINK.
The following statement illustrates a request to transfer control to PROGRAMD and passes three data items (FIELD-1, FIELD-2, and FIELD-3) to the program; the issuing program does not expect return of control:
TRANSFER CONTROL TO 'PROGRAMD' NORETURN USING FIELD-1 FIELD-2 FIELD-3.
After completion of the TRANSFER CONTROL function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
3020 |
The request cannot be serviced because an I/O, program-not-found, or potential deadlock error has occurred |
The WAIT statement relinquishes control either to CA IDMS, pending completion of one or more events, or to a higher priority ready-to-run task. If control is relinquished to wait for the completion of one or more events, an event control block (ECB) must be defined for each event. If an ECB is already posted when the WAIT is issued, the task is redispatched immediately and control does not pass to another task.
►►─── WAIT ─┬────────────────────────────────────────┬─ . ────────────────────►◄
│ ┌─────────────┐ │
├─┬─ LONG ◄ ─┬───┬─▼─ EVENT ecb ─┴─────┬─┤
│ └─ SHORT ──┘ └─ EVENT NAME ecb-id ─┘ │
│ │
└─ REDISPATCH ───────────────────────────┘
Specifies that the wait is expected to be long-term.
This is the default.
LONG should be specified for all waits expected to last a second or more (for example, terminal input).
Specifies that the wait is expected to be short-term. SHORT should be specified for all waits expected to last less than a second (for example, a disk I/O).
Defines one or more ECBs upon which the task will wait.
The symbolic name of a user-defined area that contains three PIC S9(8) COMP SYNC (fullword) fields.
Multiple EVENT parameters must be separated by at least one blank.
Specifies the ECB upon which the task will wait.
Either the symbolic name of a user-defined field that contains the ECB ID or the ID itself enclosed in quotation marks.
You cannot specify multiple EVENT NAMEs.
Specifies that the issuing task wishes to relinquish control to any higher priority ready-to-run task before being redispatched.
The following example requests a short-term wait on the event PODB:
WAIT SHORT EVENT NAME 'PODB'.
After completion of the WAIT function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
3101 |
To wait on the specified ECB would cause a deadlock |
The WRITE JOURNAL statement writes a task-defined record to the journal file. Records written to the journal file with the WRITE JOURNAL function will be available to user-defined exit routines during a task- or system-initiated rollback.
►►─── WRITE JOURNAL ─┬────────────┬───────┬──────────┬────────────────────────►
├─ WAIT ─────┤ ├─ SPAN ◄ ─┤
└─ NOWAIT ◄ ─┘ └─ NOSPAN ─┘
►─── FROM record-location ─┬─ TO end-record-location ─┬─ . ──────────────────►◄
└─ LENGTH record-length ───┘
Specifies that the issuing task will wait for completion of the physical I/O associated with the WRITE JOURNAL function before resuming execution. This option will cause CA IDMS to write a partially filled buffer to the journal file.
Specifies that the issuing task will not wait for completion of the WRITE JOURNAL function; the journal record will remain in a storage buffer until a future request necessitates writing the buffer to the journal file.
This is the default.
Specifies to write the record across several journal file blocks, if necessary.
This is the default.
Specifies to write the record to a single journal file block; if it is longer than the journal block, the record will be split.
When a record is shorter than a journal file block, based on space available in the current journal block, CA IDMS will either place the record in the block, split it across multiple blocks (SPAN), or write it to a new block after the current block is written (NOSPAN).
The following considerations apply to using an exit routine to retrieve journal file records during recovery:
Note: In general, the SPAN option provides better space utilization in the journal file because it increases the average fullness of each block.
Defines the WORKING-STORAGE SECTION or LINKAGE SECTION entry of the record to be written to the journal file.
The symbolic name of a user-defined field.
Indicates the end of the record area to be written to the journal file.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the record being written to the journal file.
Defines the length in bytes of the record to be written to the journal file.
Either the symbolic name of the user-defined field that contains the length or the length itself expressed as a numeric constant.
The following statement illustrates a request to write the JOURNAL-DATA record to the journal file, spanning it across several blocks if necessary:
WRITE JOURNAL SPAN FROM JOURNAL-DATA TO END-JOURNAL-DATA.
After completion of the WRITE JOURNAL function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
5002 |
Storage is not available for the required control blocks |
|
5032 |
The derived length of the specified journal record is zero or negative |
|
5097 |
An invalid status has been received from DBIO/DBMS; check the DC system log for details |
The WRITE LINE TO TERMINAL statement illustrates a request to transfer data from program variable storage to a terminal. WRITE LINE TO TERMINAL also establishes, modifies, and deletes page header lines.
Data transfers requested by WRITE LINE TO TERMINAL statements can be synchronous or asynchronous:
The transfer of a line to the buffer will result in a processing delay; however, control returns to the program immediately following the request. If the line of data fills the buffer, the entire page of data must be transmitted to the terminal. In this case, control does not return to the issuing program until the user responds by pressing ENTER. Thus, the program is made conversational.
With asynchronous requests, programs can buffer all required pages of output without suspending task execution during the actual transmission of data. However, the task can optionally terminate itself, thereby freeing resources and allowing the user to review the buffered output.
I/O requests are processed in the sequence received from the task; thus, if a program issues a synchronous WRITE LINE TO TERMINAL request after issuing one or more asynchronous requests, all I/O requests are completed before returning control to the issuing program.
The WRITE LINE TO TERMINAL request issued automatically by CA IDMS to empty partially filled buffers upon completion of a task is synchronous; therefore, the user can view all screens and catch up with processing at that time. If an application allows the user to interrupt or terminate processing at some point within a task, a synchronous WRITE LINE TO TERMINAL request must be issued to suspend processing while awaiting an operator response.
►►─── WRITE LINE TO TERMINAL ─────────────────────────────────────────────────►
►─┬──────────┬────┬───────────┬────┬──────────────┬──────────────────────────►
├─ WAIT ◄ ─┤ ├─ NEWPAGE ─┤ └─ NOBACKPAGE ─┘
└─ NOWAIT ─┘ └─ ERASE ───┘
►─── FROM output-data-location ─┬─ TO end-output-data-location ─┬────────────►
└─ LENGTH output-data-length ───┘
►─┬─────────────────────────────┬─ . ────────────────────────────────────────►◄
└─ HEADER header-line-number ─┘
Specifies that the write operation is synchronous; the issuing task automatically relinquishes control and must wait for completion of the output operation before processing can continue.
This is the default.
Specifies that the write operation is asynchronous; the issuing task continues executing.
Write the output data line beginning on a new page. For 3270-type devices, the NEWPAGE option forces CA IDMS to output the contents of the current buffer, even if the buffer is not full.
NEWPAGE and ERASE are synonyms and can be used interchangeably.
3270-type devices only. Does not keep pages output in a scratch area. If NOBACKPAGE is specified, the user can view only the current page of output. NOBACKPAGE is valid only with the first I/O request in a line mode session.
Identifies the WORKING-STORAGE SECTION or LINKAGE SECTION entry of the data to be transferred to the terminal device or the page header line being created, modified, or deleted.
The symbolic name of a user-defined field.
Indicates the end of the WORKING-STORAGE SECTION or LINKAGE SECTION entry that contains the output data stream.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the output data.
Defines the length in bytes of the output data area.
Either the symbolic name of a user-defined field that contains the length of the data area or the length itself expressed as a numeric constant.
Note: If the WRITE LINE TO TERMINAL statement is being used to delete a page header line, output-data-length must be zero.
Specifies the number of the page header line being created, modified, or deleted.
Either the symbolic name of a user-defined field that contains the header line number or the header line number itself expressed as a numeric constant.
The following examples illustrate the use of the WRITE LINE TO TERMINAL statement.
The following statement defines the value of a data area as a header to be displayed at the top of each new page written to the terminal:
WRITE LINE TO TERMINAL FROM EMPL-HEAD TO END-EMPL-HEAD HEADER 1.
The following statement illustrates a request to write the value in the specified data area to a new page on the terminal:
WRITE LINE TO TERMINAL NOWAIT FROM EMPL-RPT LENGTH 60.
After completion of the WRITE LINE TO TERMINAL function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
4707 |
A logical or permanent I/O error has occurred during processing. |
|
4731 |
The line request block (LRB) contains an invalid field, indicating a possible error in the program's parameters. |
|
4732 |
The derived length of the specified line output area is zero or negative. |
|
4738 |
The specified 01-level LINKAGE SECTION entry has not been allocated as required. A GET STORAGE request must be issued. |
|
4743 |
The line I/O session has been canceled; the user has pressed CLEAR (3270s), ATTENTION (2741s), or BREAK (teletypes). |
The WRITE LOG statement retrieves a predefined message from the message area of the data dictionary and optionally writes the message to a specified location in program variable storage. Retrieved messages are sent to the destination specified in the message definition; typical destinations are the operator's console and the DC system log file. If the operator's console has been defined as the message destination, the WRITE LOG statement can request a reply. When a reply is requested, control is not returned to the issuing task until the reply is received.
Note: For more information about global messages, see the CA IDMS IDD DDDL Reference Guide.
The message ID specified in the WRITE LOG statement is a seven-digit number. The first six (most significant) digits make up the actual message ID used to retrieve the message from the data dictionary; the seventh digit is a severity code. This severity code is predefined in the dictionary and is retrieved along with the message text to indicate the action to be taken after the message is written to the log:
|
Severity Level |
CA IDMS Action |
|---|---|
|
0 |
Return control to the issuing program and continue processing |
|
1 |
Snap all task resources and return control to the issuing program |
|
2 |
Snap all system areas and return control to the issuing program |
|
3 |
Snap all task resources and abend the task with a task abend code of D002 |
|
4 |
Snap all system areas and abend the task with a task abend code of D002 |
|
5 |
Terminate the task with a task abend code of D002 |
|
6 |
Undefined |
|
7 |
Undefined |
|
8 |
Snap all system areas and abend the system with a system abend code of 3996 |
|
9 |
Terminate the system with a system abend code of 3996 |
If a WRITE LOG statement specifies a message ID that is not in the data dictionary, CA IDMS will use a prototype message but will perform the action associated with the severity code specified in the WRITE LOG request.
Messages stored in the data dictionary can contain symbolic parameters. Symbolic parameters, identified by an ampersand (&). followed by a two-digit numeric identifier, can appear in any order within the message. The WRITE LOG statement can specify replacement values for one or more symbolic parameters; however, the position of replacement values within the WRITE LOG request must correspond exactly with the two-digit numeric identifier in the message text. For example, the first value specified corresponds to &01., the second to &02., and so forth.
►►─── WRITE LOG MESSAGE ID message-id ────────────────────────────────────────►
►─┬───────────────────────────────────────────────────────────────────────┬──►
│ ┌───────────────────────────────────────────────────────────┐ │
└─ PARMS ─▼─ FROM parameter-location ─┬─ TO end-parameter-location ─┬─┴─┘
└─ LENGTH parameter-length ───┘
►─┬───────────────────────────────────────────────────────────────┬──────────►
└─ REPLY INTO reply-location ─┬─ TO end-reply-location ───────┬─┘
└─ MAX LENGTH reply-max-length ─┘
►─┬────────────────────────────┬─────────────────────────────────────────────►
└─ MESSAGE PREFIX is 'DC' ───┘
►─┬──────────────────────────────────────────────────────────────────────────►─
└─ TEXT INTO text-return-location ─┬─ TO end-text-return-location ─┬───────
└─ MAX LENGTH text-max-length ──┘
─►───────────────────────────────────────────────┬─ . ───────────────────────►◄
───┬──────────────────────────────────────────┬─┘
├─ MESSAGE PREFIX is ─┬─ YES ◄ ──────────┬─┤
│ ├─ NO ─────────────┤ │
│ └─ message-prefix ─┘ │
│ │
└─ TEXT is ONLY ───────────────────────────┘
Specifies the message ID. The first six digits specify the ID of the message; the seventh digit specifies the message's severity code.
Either the symbolic name of a user-defined PIC S9(8) COMP (fullword) field that contains the message ID or the ID itself expressed as a numeric constant.
Message IDs 000001 through 900000 are reserved for use by CA IDMS; the WRITE LOG statement can specify any number in the range 900001 through 999999.
Caution: The message length must be seven digits. The system will always interpret the last digit as the severity level. If you request message 987659 and do not code a severity level of zero (that is, 9876590) you are actually requesting that message 098765 be written to the log and that the system should be terminated with a 3996 abend code.
When messages are added to the data dictionary for use with the WRITE LOG statement, they are assigned an eight-character identification number; the first two characters are DC. A request for message 987654 retrieves DC987654.
Supplies replacement values for one or more symbolic parameters stored with the message text.
The symbolic name of a user-defined field that contains the WORKING-STORAGE SECTION or LINKAGE SECTION entry of the replacement parameter.
This field must begin with a one-byte field into which the system places the length of the adjacent field. The value in the length does not include the length byte.
Indicates the end of the WORKING-STORAGE SECTION or LINKAGE SECTION entry that contains the replacement parameter.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the replacement parameter.
Defines the length, in bytes, of the replacement parameter.
Either the symbolic name of a user-defined field that contains the length or the length itself expressed as a numeric constant.
Specifies the WORKING-STORAGE SECTION or LINKAGE SECTION entry of the area reserved for a reply to the message issued by the WRITE LOG request.
The symbolic name of a user-defined field.
This field must begin with a one-byte field into which the system places the length of the adjacent field. The value in the length does not include the length byte.
Indicates the end of the WORKING-STORAGE SECTION or LINKAGE SECTION entry reserved for the reply.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the reply.
Defines the maximum length, in bytes, of the area reserved for the reply.
Either the symbolic name of a user-defined field that contains the length or the length itself expressed as a numeric constant.
Specifies the two characters that precede the numeric position of a message. The default is 'DC'.
Specifies that the contents of the named message, along with any replacement parameters, are to be written to the issuing program.
The symbolic name of a user-defined 1 through 132 character alphanumeric field that contains the WORKING-STORAGE SECTION or LINKAGE SECTION entry to which the message text is to be returned.
This field must begin with a 1-byte field into which the system places the length of the adjacent field. The value in the length does not include the length byte.
Indicates the end of the WORKING-STORAGE SECTION or LINKAGE SECTION entry reserved for the text.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the returned text.
Defines the maximum length in bytes of the WORKING-STORAGE SECTION or LINKAGE SECTION entry reserved for the returned message text.
Either the symbolic name of a user-defined field that contains the text length or the length itself expressed as a numeric constant.
Defines the format of the message prefix. To override the default DC prefix, specify any one or two characters for message-prefix. To suppress a prefix, specify blanks.
Indicates that the message text is preceded by:
IDMS ppnnnnnnn Vssssss REPLYnn
This is the default.
Indicates that the message text is preceded by:
ppnnnnnnn
Indicates that the message text is output with no prefix.
The following figure illustrates a WRITE LOG statement that supplies three replacement parameters.
Task A issues a WRITE LOG request for message 900121, specifying values to replace symbolic parameters &01., &02., and &03. stored with the message text. The message is sent to its destination, which has been defined as the logical terminal associated with the issuing task.
After completion of the WRITE LOG function, the ERROR-STATUS field of the IDMS DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
3623 |
No storage or resource control element (RCE) can be allocated for the specified reply area |
|
3624 |
The maximum number of outstanding replies has been exceeded; a maximum of 98 messages can be awaiting reply at a given time |
|
3625 |
The maximum number of replacement parameters has been exceeded; a maximum of 8 replacement parameters may be used if the "Message Prefix" option is not used. If the"Message Prefix" option is used then the maximum number of replacement parameters is limited to 7. |
|
3631 |
The parameter list is invalid |
The WRITE PRINTER statement transmits data from a task to a terminal defined to the system as a printer device during system generation. Any type of terminal can be designated as a printer; however, the terminal is usually a hard-copy device.
CA IDMS does not transmit data directly from program variable storage to the terminal. Rather, data is passed to a queue maintained by CA IDMS, and from the queue to the printer. The data stream passed to the queue by the WRITE PRINTER request contains only data; CA IDMS adds the necessary line and device control characters when it writes the data to the printer.
Note: Native mode data streams (that is, those that contain device-control information as well as user data) can also be transmitted with a WRITE PRINTER request. This capability is useful in formatting reports for 3280-type printers.
Each line of data transmitted in a WRITE PRINTER request is considered a record. Each record is associated with a report in the print queue. A report consists of one or more records. Any task can have up to 256 active print reports. A program can issue multiple WRITE PRINTER requests, each specifying a different report. Because the records associated with each report are maintained individually, records associated with one report are not interspersed with records associated with other reports when printed.
The WRITE PRINTER request can direct reports to print classes and to destinations:
A report is printed only when that report is completed, either explicitly as part of a WRITE PRINTER request or implicitly when the issuing task terminates.
Note: Normal task termination, a FINISH TASK request, or a COMMIT TASK request will end all of the task's reports. Queued reports are made eligible for printing.
Abnormal task termination (abend) or a ROLLBACK TASK request will cause any queued reports belonging to the task to be deleted.
►►─── WRITE PRINTER ─┬───────────┬────┬──────────┬────────────────────────────►
├─ NEWPAGE ─┤ └─ ENDRPT ─┘
└─ ERASE ───┘
►─┬──┬──────────┬─ FROM message-location ─┬─ TO end-message-location ─┬──┬───►
│ └─ NATIVE ─┘ └─ LENGTH message-length ───┘ │
│ │
└─ SCREEN CONTENTS ────────────────────────────────────────────────────┘
►─┬───────────────────────────┬─────┬─────────────────────────────┬──────────►
└─ COPIES ─┬─ 1 ◄ ────────┬─┘ └─ REPORT ID ─┬─ 1 ◄ ───────┬─┘
└─ copy-count ─┘ └─ report-id ─┘
►─┬─────────────────────────────────────────────┬────────────────────────────►
├─ CLASS printer-class ───────────────────────┤
└─ DESTINATION printer-destination ─┬───────┬─┘
└─ ALL ─┘
►─┬────────┬────┬────────┬─ . ───────────────────────────────────────────────►◄
└─ HOLD ─┘ └─ KEEP ─┘
Specifies that the data stream will be printed beginning on a new page.
NEWPAGE and ERASE are synonyms and can be used interchangeably.
Indicates that the data stream constitutes the last record in the specified report. When ENDRPT is specified, the report can be printed before the issuing task has terminated. However, the program must issue a COMMIT TASK request to signal to print the ended report. A subsequent WRITE PRINTER request with the same report ID will start a separate report.
Specifies that the data stream contains device control characters. If NATIVE is not specified, the necessary characters are automatically inserted.
Specifies the WORKING-STORAGE SECTION or LINKAGE SECTION entry of the data to be transmitted to the print queue.
The symbolic name of a user-defined field.
Indicates the end of the WORKING-STORAGE SECTION or LINKAGE SECTION entry that contains the data to be transmitted to the print queue.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the output data.
Defines the length, in bytes, of the data stream.
Either the symbolic name of a user-defined field that contains the length of the data or the length itself expressed as a numeric constant.
3270-type devices only. Specifies that the contents of the currently displayed screen are to be transmitted to the print queue.
Specifies the number of copies of the report to be printed.
Either the symbolic name of a user-defined field that contains the copy count or the count itself expressed as a numeric constant.
The count must be an integer in the range 1 through 255; the default is one.
Specifies the identifier of the report to be printed.
Either the symbolic name of a user-defined field that contains the report ID or the ID itself expressed as a numeric constant. Report-id must be an integer in the range 1 through 255; the default is one.
Specifies the print class to which the report will be assigned.
The CLASS or DESTINATION should be specified only for the first line of each report. If no class or destination is specified, the default print class assigned to the issuing task's physical terminal during system generation will be used.
Either the symbolic name of a user-defined field that contains the print class or the class itself expressed as a numeric constant.
Valid print classes are 1 through 64; the default is 1.
Specifies the destination to which the report will be routed.
The CLASS or DESTINATION should be specified only for the first line of each report. If no class or destination is specified, the default print class assigned to the issuing task's physical terminal during system generation will be used.
Either the symbolic name of a user-defined field that contains the destination or the destination itself enclosed in quotation marks.
The specified destination must have been defined during system generation.
ALL Specifies that the report is to be printed on all of the printers belonging to the specified destination. The report will be printed, one printer at a time, and saved until it has been printed on each of the printers associated with the destination.
Specifies that a queued report will be held without being printed. The specified report will be held until a DCMT VARY REPORT report-name RELEASE command is issued at run time.
Specifies to keep the report in the print queue after it has been printed. The report can be released for printing with a DCMT VARY REPORT report-name RELEASE command. In this way, the report can be printed several times. A KEPT report can be deleted from the print queue manually (using a DCMT VARY REPORT report-name DELETE command at run time) or automatically (when the queue retention period has been exceeded).
The following examples illustrate the use of the WRITE PRINTER statement.
The following statement illustrates a request to associate the data in the specified location with report 32 in the print queue and to print it beginning on a new page. Report 32 will print on the first terminal assigned to print class 3 when the program notifies CA IDMS that the report is complete or when the task terminates.
WRITE PRINTER NEWPAGE FROM PASSGR-RPT TO END-PASSGR-RPT REPORT ID 32 CLASS 3.
The following statement illustrates a request to print three copies of the current screen contents on a printer associated with destination A and to keep the contents of the report in the print queue after it has printed:
WRITE PRINTER SCREEN CONTENTS COPIES 3 DESTINATION 'A' KEEP.
After completion of the WRITE PRINTER function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully. |
|
4807 |
An I/O error has occurred while placing the record in the print queue. |
|
4818 |
The current DC system definition contains no logical terminal-printer associations. |
|
4821 |
The specified printer destination is undefined or is not a printer. |
|
4831 |
The parameter list is invalid. |
|
4832 |
The derived length of the specified printer output data area is zero or negative. |
|
4838 |
The specified 01-level LINKAGE SECTION entry has not been allocated, as required. A GET STORAGE request for the specified variable must be issued before the WRITE PRINTER statement. |
|
4845 |
A WRITE PRINTER SCREEN CONTENTS request cannot be serviced because the terminal associated with the issuing task is not a 3270-type device or is a remote 3270 device running under TCAM. |
|
4846 |
A terminal I/O error has occurred. |
The WRITE TERMINAL statement requests a synchronous or asynchronous data transfer from program variable storage to the terminal buffer.
►►─── WRITE TERMINAL ───┬──────────┬──────────────────────────────────────────►
├─ WAIT ◄ ─┤
└─ NOWAIT ─┘
►─┬─────────────────────────────┬─────┬────────────────┬─────────────────────►
├─┬─ NEWPAGE ─┬───────────────┤ └─ FREE STORAGE ─┘
│ └─ ERASE ───┘ │
│ │
└─┬─ EAU ───────────────────┬─┘
└─ ERASE ALL UNPROTECTED ─┘
►─── FROM output-data-location ─┬─ TO end-output-data-location ─┬─ . ────────►◄
└─ LENGTH output-data-length ───┘
Specifies that the write operation will be synchronous; the issuing task will automatically relinquish control to CA IDMS and wait for completion of the write operation before continuing processing.
This is the default.
Specifies that the write operation will be asynchronous; the issuing task will continue executing.
Note: If NOWAIT is specified, the program must issue a CHECK TERMINAL request (described earlier in this chapter) before performing any other I/O operation.
Activates the page-eject (SYSINOUT devices) or erase-write (3270-type devices) mechanism to erase the contents of a screen. If NEWPAGE is not specified, the WRITE TERMINAL request will write over rather than erase data displayed on the terminal.
NEWPAGE and ERASE are synonyms and can be used interchangeably.
3270-type devices only. Activates the erase-all-unprotected mechanism. Following a WRITE TERMINAL EAU function, only protected fields remain on the terminal. If EAU is specified, the FROM clause (described below) need not be specified.
EAU and ERASE ALL UNPROTECTED are synonyms and can be used interchangeably.
Releases the output buffer associated with the data being written to the terminal. The storage area being freed must have been acquired by a GET STORAGE statement (described earlier in this chapter) or the GET STORAGE option of a previously issued READ TERMINAL or WRITE THEN READ TERMINAL request. If FREE STORAGE is not specified, the storage associated with the output buffer is not freed until the issuing task terminates.
Specifies the 01-level WORKING-STORAGE SECTION or LINKAGE SECTION entry of the output data stream.
The symbolic name of a user-defined field. If FREE STORAGE is specified, output-data-location must be an 01-level LINKAGE SECTION entry.
Indicates the end of the output data stream and is specified following the last data-item entry in output-data-location.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the output data stream.
Defines the length in bytes of the output data stream.
Either the symbolic name of a user-defined field that contains the length of the data area or the length itself expressed as a numeric constant.
The following statement illustrates an asynchronous basic mode request to write data to the terminal from the specified location in program variable storage:
WRITE TERMINAL NOWAIT FROM TERM-LINE LENGTH 72.
After completion of the WRITE TERMINAL function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
4525 |
The output operation has been interrupted; the user has pressed ATTENTION or BREAK |
|
4526 |
A logical error (for example, an invalid control character) has been encountered in the output data stream |
|
4527 |
A permanent I/O error has occurred during processing |
|
4528 |
The dial-up line for the terminal has been disconnected |
|
4531 |
The terminal request block (TRB) contains an invalid field, indicating a possible error in the program's parameters |
|
4532 |
The derived length of the specified output data area is zero or negative |
|
4537 |
Storage for the output buffer cannot be freed because the specified data area is defined in the WORKING-STORAGE SECTION rather than in the LINKAGE SECTION. |
|
4539 |
The terminal associated with the issuing task is out of service |
The WRITE THEN READ TERMINAL statement requests a transfer of data from program variable storage to the terminal buffer and, when the user has completed entering data, a transfer of that data back to program variable storage.
►►─── WRITE THEN READ TERMINAL ───┬──────────┬────────────────────────────────►
├─ WAIT ◄ ─┤
└─ NOWAIT ─┘
►─┬─────────────────────────────┬─────┬────────────────┬─────────────────────►
├─┬─ NEWPAGE ─┬───────────────┤ └─ FREE STORAGE ─┘
│ └─ ERASE ───┘ │
│ │
└─┬─ EAU ───────────────────┬─┘
└─ ERASE ALL UNPROTECTED ─┘
►─── FROM output-data-location ─┬─ TO end-output-data-location ─┬────────────►
└─ LENGTH output-data-length ───┘
►─┬────────────────────────────────────────────────────┬─────────────────────►
└─┬─ MODIFIED ─┬─┬─────────────────────────────────┬─┘
└─ BUFFER ───┘ └─ FROM POSITION screen-position ─┘
►─┬───────────────┬──────────────────────────────────────────────────────────►
└─ GET STORAGE ─┘
►─── INTO input-data-location ─┬─ TO end-input-data-location ───────┬────────►
└─ MAX LENGTH input-data-max-length ─┘
►─┬───────────────────────────────────────────────┬─ . ──────────────────────►◄
└─ RETURN LENGTH into input-data-actual-length ─┘
Specifies that the I/O operation will be synchronous; the issuing task will automatically relinquish control to CA IDMS and must wait for completion of the I/O operation before processing can continue.
This is the default.
Specifies that the I/O operation will be asynchronous; the issuing task will continue executing.
Note: If NOWAIT is specified, the program must issue a CHECK TERMINAL request (described earlier in this chapter) before performing any other I/O operation.
Activates the page-eject (SYSINOUT devices) or erase-write (3270-type devices) mechanism to erase the contents of a screen. If NEWPAGE is not specified, the WRITE TERMINAL request will write over rather than erase data displayed on the terminal.
NEWPAGE and ERASE are synonyms and can be used interchangeably.
3270-type devices only. Activates the erase-all-unprotected mechanism. Following a WRITE TERMINAL EAU function, only protected fields remain on the terminal. If EAU is specified, the FROM clause (described below) need not be specified.
EAU and ERASE ALL UNPROTECTED are synonyms and can be used interchangeably.
Releases the output buffer associated with the data being written to the terminal. The storage area being freed must have been acquired by a GET STORAGE statement (described earlier in this chapter) or the GET STORAGE option of a previously issued READ TERMINAL or WRITE THEN READ TERMINAL request. If FREE STORAGE is not specified, the storage associated with the output buffer is not freed until the issuing task terminates.
Specifies the 01-level WORKING-STORAGE SECTION or LINKAGE SECTION entry of the output data stream.
The symbolic name of a user-defined field. If FREE STORAGE has been specified, output-data-location must be an 01-level LINKAGE SECTION entry.
Indicates the end of the output data stream.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the output data stream.
Defines the length in bytes of the output data stream.
Either the symbolic name of a user-defined field that contains the length of the data stream or the length itself expressed as a numeric constant.
3270-type devices only. Reads all modified fields in the terminal buffer into program variable storage.
3270-type devices only. Executes a READ BUFFER command that reads the entire contents of the terminal buffer into the program variable storage.
Defines the buffer address (screen position) at which the read will start.
Either the symbolic name of a user-defined PIC S9(8) COMP SYNC (fullword) field or the address itself enclosed in quotation marks.
Synchronous requests only. Acquires an input buffer for the data being read into the program; CA IDMS allocates the required storage when the read operation is complete.
Specifies the 01-level WORKING-STORAGE SECTION or LINKAGE SECTION entry of the data area reserved for the input data stream.
The symbolic name of a user-defined field.
If GET STORAGE is specified, the data area reserved for the input data stream must be an unallocated 01-level LINKAGE SECTION entry. If GET STORAGE is not specified, the data area must be a WORKING-STORAGE SECTION or previously allocated LINKAGE SECTION entry.
Indicates the end of the data area reserved for the input data stream.
The symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the data area reserved for the input data stream.
Defines the length, in bytes, of the data area reserved for the input data stream.
Either the symbolic name of a user-defined field that contains the length of the data stream or the length itself expressed as a numeric constant.
If the input data stream is larger than the data area reserved in the WORKING-STORAGE SECTION or LINKAGE SECTION, the data stream is truncated to fit the available space.
Indicates the location to which CA IDMS will return the actual length of the input data stream.
The symbolic name of a user-defined field. If the data stream has been truncated, input-data-actual-length contains the original length before truncation.
The following statement illustrates a basic mode request to write data from the program (OUTPUT-LINE) to the terminal, read the data from the terminal to the specified location (INPUT-LINE) in the program, and return the actual length of the input data stream (LINE-LENGTH) to variable storage:
WRITE THEN READ TERMINAL WAIT FROM OUTPUT-LINE TO END-INPUT-LINE INTO INPUT-LINE MAX LENGTH 80 RETURN LENGTH INTO LINE-LENGTH.
After completion of the WRITE THEN READ TERMINAL function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome of the operation:
|
Status code |
Meaning |
|---|---|
|
0000 |
The request has been serviced successfully |
|
4519 |
The input area specified for the return of data is too small; the returned data has been truncated to fit the available space |
|
4525 |
The output operation has been interrupted; the terminal operator has pressed ATTENTION or BREAK |
|
4526 |
A logical error (for example, an invalid control character) has been encountered in the output data stream |
|
4527 |
A permanent I/O error has occurred |
|
4528 |
The dial-up line for the terminal has been disconnected |
|
4531 |
The terminal request block (TRB) contains an invalid field, indicating a possible error in the program's parameters . |
|
4532 |
The derived length of the specified I/O data area is zero or negative. |
|
4535 |
Storage for the input buffer cannot be acquired because the specified 01-level LINKAGE SECTION entry has been allocated |
|
4537 |
A storage area cannot be acquired or freed because the specified data area is defined in the WORKING-STORAGE SECTION rather than in the LINKAGE SECTION |
|
4538 |
The specified 01-level LINKAGE SECTION entry has not been allocated and the GET STORAGE option has not been specified |
|
4539 |
The terminal device associated with the issuing task is out of service |
Logical-record clauses are used with any of the four DML statements that access logical records (that is, OBTAIN, MODIFY, STORE, or ERASE). The logical-record clauses are as follows:
|
Copyright © 2014 CA.
All rights reserved.
|
|