Edit DL/1 Segment (5.4.4)

The Edit DL/1 Segment screen (5.4.4) is used to access a segment in a DL/I database, and if authorized, modify the segment. Data can be displayed in character, vertical hexadecimal, or dump format.

Standard DL/I notation is used to access the data using SSAs. In addition, Code Debug CICS can build skeleton SSAs for use in accessing a segment, or rebuild complete SSAs displaying the path to the segment.

File mapping is available on this screen. See USING for more information on file mapping.

This screen can be used to perform actual DL/I calls to a database. The PSB name and PCB number are required to perform any calls. These fields can be entered or automatically supplied by Code Debug CICS by proceeding through the previous screens in the DL-1-Database-Menu-5-4 functions.

Access this screen by typing the number 4.4 on the File-Utility-Menu-5, or typing 4 on the DL-1-Database-Menu-5-4, or as described in Transferring Between Screens.

Edit DL/1 Segment Screen (5.4.4)

You must use the PCB to schedule a PSB before making any calls against a database. You can make any changes you want while the PSB is scheduled. To commit those changes to the database, you can use either the TERM command or the END command. If you want to cancel changes while the PSB is still scheduled, use the CANCEL command. All changes will be rolled back. The same CANCEL action will occur if you transfer to another screen or the scheduled PSB times out.

The handling of DL/I data has been enhanced in Code Debug CICS to allow you to roll back changes in progress. Changes are committed only as follows:

• By issuing a TERM command while a PSB is scheduled
• By issuing the END command. This automatically issues a TERM call and transfers back to the previous screen.

If you do not want changes to be committed, you can prevent them in either of two ways.

• Issue the CANCEL command while a PSB is scheduled.
• Transfer from the Edit DL/1 Segment screen with a command such as =2.L.

In either case, Code Debug CICS will force an abend (without a dump). This will cause DL/I dynamic transaction backout processing to be invoked. DBFL, an asynchronous transaction that performs Code Debug file utility I/O calls, as well as XPED, XPRT, and XPSP all must have dynamic transaction backout specified.

Code Debug CICS uses standard DL/I notation to perform calls. READ and WRITE commands are not used.

Input Fields

PSBNAME

PSB used to define a set of DL/I databases that can be accessed from a program. When a PSB name is selected from the DL/1 PSB List (5.4.1) screen, Code Debug CICS automatically displays it in this field. You may also enter a valid PSB name in this field. Code Debug CICS checks the PSB name and displays an error message if it is invalid for the CICS region or the DBCTL region to which this CICS region is connected. Always select a PSB to access a DL/I database.

PCB#

Number of the PCB in the selected PSB. Code Debug CICS uses the PCB number instead of the DBD name because multiple PCBs can access the same DBD using the same or slightly different views of the database.

When a DBCTL PSB is selected from the DL/1 PCB List (5.4.2) screen, Code Debug CICS automatically displays it in this field. If no selection was made, enter a two-digit PCB number, relative to 1, for the PCB to be accessed in the displayed PSB. Code Debug CICS checks the number and displays an error message if it is invalid.

HEX/DEC-OFFSET

Displays the current offset within the column’s data. This value is always relative to 0. The data display begins at this offset. This field may be modified. The value entered must be in the range of 0 to the decimal value displayed in the RECLN field. When HEX-OFFSET is displayed, the value will be between 0 and the hexadecimal equivalent of the decimal value displayed in the RECLN field. In addition, when DEC-OFFSET is displayed, a hexadecimal value with a leading positive (+) sign may be entered instead, e.g. 80 or +50 are equivalent.

ADD-OFFSET

Use with the HEX/DEC-OFFSET field to provide a new starting offset into the I/O area. The entered value is added to the value in the HEX/DEC-OFFSET field to yield a new starting offset value. If the entered value has a leading minus sign (-), the entered value is subtracted from the value in the HEX/DEC-OFFSET field.

If the display mode is HEX DUMP mode, only hexadecimal values can be entered. If the display mode is character (HEX OFF) or vertical hexadecimal (HEX ON), the value can be entered either in decimal or hexadecimal. This can be done by preceding the value with a plus sign (+). To add a negative offset, precede the value by a minus sign (-). A value preceded by a minus sign is treated as decimal when in HEX ON or HEX OFF mode and as hexadecimal when in HEX DUMP mode.

I/O area

Data from the Code Debug CICS I/O area that can be displayed in four modes. Each mode supports different scrolling commands, as displayed in File Utility Scrolling Commands. For more information, see Using the Code Debug CICS I/O Area.

SSA Area

SSAs in a DL/I call allow you to provide information to DL/I that satisfies the call. Specify the following information in an SSA:

• Name of the segment type
• Description of a specific segment in a qualifying statement
• One or more qualifying command codes.

A DL/I call with one or more SSAs is a qualified call. A DL/I call with no SSAs is an unqualified call. Similarly, there are two types of SSAs:

• Unqualified SSA: An SSA that contains only a segment name is an unqualified SSA. A segment name less than 8 bytes in length must be padded with blanks to the right. The segment name is followed by at least one blank. An unqualified SSA only defines the segment type to be processed, not an actual occurrence of the segment.
• Qualified SSA: In addition to the segment name, a qualified SSA contains one or more qualification statements. A qualified SSA contains the sections as displayed in the following table with the specified number of bytes.

Qualified SSA Sections

A qualification statement provides DL/I with information about a specific segment occurrence. Give DL/I the name of a field in the segment and the value of a specific field. The field and the value are connected by a relational operator (RO) that tells DL/I how to compare the two. The qualification portion of the SSA is enclosed in parentheses.

A sample SSA as displayed in the SSA area is:

The fields of the SSA area are:

LV

Hierarchical level in the SSA list. This number is the level in the database that the SSA references. Code Debug CICS automatically calculates and displays the value. This field can be used to modify the order of SSAs, and insert and delete SSAs with line commands.

SEG NAME

Name of the segment accessed at this level in the database. This field is eight bytes. If the desired segment name is less than 8 bytes, enter blanks on the right.

CC (Command Code)

Optional qualifiers for DL/I. Valid entries are four alphanumeric characters. If used in a qualified SSA, the first position must be an asterisk (*). Code Debug CICS limits the use of command codes to the following subset:

• 
  
  • null: If command codes are not being used, type the command code field as *--- (asterisk and dashes). If blanks are entered, Code Debug CICS converts them to dashes.
  • C: Specifies that DL/I is supplied with a segment’s concatenated key for identification, instead of a qualification statement. Use either the C command code or a qualification statement, but not both. When entering the concatenated key, enclose it in parentheses following the *C.

  • The C command code may be easier than creating qualified SSAs for all higher level segments required in the hierarchical path to reach the desired segment. For more information, see the IBM documentation site.

  • F: Retrieves the first occurrence of a segment type, or inserts a new segment occurrence as the first occurrence in a chain of segments. The F command code allows GN or GNP calls to back up in the database.
  • L: Retrieves the last occurrence of a certain segment type under its parent. It can also be used to insert a segment as the last occurrence of a segment type.
  • U: Qualifies a call with the current position at one level. The U command code specifies that DL/I will use no occurrence of the segment type specified in the SSA under the current parent segment type, other than occurrences on which the position is already established.
  • The U command code prevents the position from being moved from a segment during a search of its hierarchical dependents. If the segment has a unique sequence field, using this code is the same as a qualified SSA that is equal to the current value of the key field. During a call, if the position is moved to a level above which the U command code is used, the code has no effect for the segment type whose parent changed position.
  • Use the U command code when processing unkeyed dependents or nonunique keyed segments. A U code can hold the position on a specific occurrence of such a segment.
  • V: Qualifies a call with the current position at all hierarchical levels. The V command code is similar to the U code except that it is set at all higher levels in the call. This means that DL/I, when attempting to satisfy this call, cannot move from the current position at the level where V is specified.
  • Q: Reserves a segment for your program’s exclusive use. The Q command code instructs DL/I to lock a segment so that no other programs can update it, even if your program does not update it.

Q (Qualifier)

Qualifier field that specifies the start of the SSA qualification statement. When building a qualified SSA, be sure that this field contains a left parenthesis ( ( ).

SEGFLD

Name of the field that DL/I uses to search for a segment. Valid entries must be eight bytes. If the search field name is less than eight bytes, enter blanks on the right.

OP (Relational Operator)

Relational operator that is two bytes long. It contains the operator that determines the comparison to be made by DL/I in attempting to satisfy the qualification statement. Valid relational operators are shown in the following table. Note that b in the table indicates a blank hex '40' character.

Relational Operators

SEARCH KEY

Value that DL/I uses in the comparison when attempting to satisfy the qualification statement. It must be the same length as that defined for the Search Field name. For a qualified SSA, a right parenthesis ( ) ) must follow the value. Code Debug CICS displays the data in this field in vertical hexadecimal format to aid in working with data that cannot be represented by a single character. When a right parenthesis is entered at the end of the key, Code Debug CICS assumes that it specifies the end of the key data and protects the remainder of the field. To extend the data in this field, type over the right parenthesis with a blank, and 256 bytes will be available for use.

Scroll left and right through the field using Code Debug CICS scrolling commands, making sure that the cursor is positioned in the bounds of this field.

SSA-Related Commands

To view the SSAs, use the SHOW KEYS or SHOW SSA primary command. When in the SSA display mode, you can modify the SSAs, reorder, and delete them. Line commands are entered in the level number field preceding each SSA.

The SHOW DATA primary command displays the segment I/O area. The data held in this area is used in REPL and ISRT calls. Any GET calls refresh the data in this area with the new segment data. For information on the I/O area, see Using the Code Debug CICS I/O Area.

The C (Copy) and M (Move) line commands are always used with an A (After) or B (Before) line command. The C and M commands are always matched with the first A or B command detected; that is, once a C or M command is detected, the SSA list is searched from the beginning until an A or B command is found.

• A (After): Destination after which an SSA is copied or moved.
• B (Before): Destination before which an SSA is copied or moved.
• C (Copy): SSA to be copied after or before another SSA.
• D (Delete): Existing SSA to be deleted from the SSA list.
• I (Insert): Inserts a dummy SSA into the SSA list. The I line command is used to insert the dummy SSA after the SSA it is coded on. The IB line command is used to insert the dummy SSA before the SSA it is coded on.
• M (Move): SSA to be moved after or before another SSA.

Output Fields

DBCTL STATUS

Displays the status of DBCTL in this CICS region.

DBCTL ID

Displays the ID of the DBCTL region to which this CICS region is connected.

COMMANDS

List of commands that can be used with DL/I segments, I/O area manipulation, and screen display modes. If PCB is the only command displayed, you must issue the PCB command to schedule the PSB. When the PSB has been scheduled, a list of available commands for accessing segment data will be displayed. If NONE shows in this area:

• No PSB is scheduled.
• Code Debug CICS cannot determine the valid DL/I commands.
• You are not authorized for Edit DL/1 Segment screen (5.4.4) functions.

To display the I/O area (segment contents) use the SHOW DATA command. To display SSA data (as displayed in Edit DL/1 Segment Screen (5.4.4)), use the SHOW SSA command. To rebuild SSAs to reflect the currently displayed segment, use the SHOW KEYS command. For more information, see Variable-and-Common-Parameters.

DBD

Name of the DBD that defines the database.

RECLN

Current length of the I/O area. The length may exceed the maximum record size for a particular resource. In this case, only the data up to the maximum record length is used. The I/O area may be truncated if an I/O command is issued.

MAX RECLN

Maximum record size that can be used for the current CICS file resource being accessed.

RECFM

Record format. Valid entries are:

• F: Fixed-length record
• V: Variable-length record.

PSB scheduling status

Message field to the right of the RECFM field that displays the scheduling status of the PSB specified in the PSBNAME field. Based on the status of the PSB, one of the following messages is displayed:

• PSB IS SCHEDULED indicates PSB is scheduled with the PCB command.
• PSB IS NOT SCHEDULED indicates PSB is not scheduled with the PCB command. The command is not issued yet, you are not authorized to use it, or an error terminated the PSB.

PCB Field Area

PCB fields for the data obtained from the PCB used in the last DL/I call. These fields reflect the current position in the database and the status returned by DL/I.

DATABASE NAME

DBD associated with the last call performed.

LV

Level number of a requested segment that DL/I has retrieved. If several segments are retrieved in a hierarchical path with one call, the number of the lowest level segment retrieved is displayed. If DL/I cannot find the requested segment, it displays the level number of the last segment it encountered that satisfied the call.

STAT CODE

Two-character status code that describes the results of the DL/I call. DL/I updates the code after each call and does not clear it between calls. There are three categories of status codes:

• 
  
  • Successful or exceptional but valid conditions. If the call is completely successful, this field contains blanks. Many of the codes in this category are for information only. For example, GB means that DL/I has reached the end of the database without satisfying the call. This situation is expected in sequential processing and is not usually the result of an error.
  • Errors in the call. For example, AK indicates an invalid field name is included in an SSA.
  • I/O or system error. For example, a NO status code indicates an I/O error concerning the access method used for the database. Contact the system programmer or DBA for these errors.

Code Debug CICS provides additional diagnostics for many of the displayed status codes. To view these diagnostics, enter HELP xx in the COMMAND line, where xx is the DL/I status code.

PROC OPTS

Four-byte code that specifies the type of calls that can be issued by this PCB. This security mechanism can prevent an update while allowing a read on the database. Valid entries are:

• 
  
  • G: Get processing
  • I: ISRT processing (adds)
  • R: REPL processing (updates)
  • D: DLET processing (deletes)
  • A: All of the above
  • GO: Read only get processing.

SEGMENT NAME

Name of the last segment that satisfied the call in this field. When a retrieval is successful, DL/I displays the name of the retrieved segment. When a retrieval is unsuccessful, DL/I displays the last segment along the path to the requested segment that satisfied the call.

KFD LEN

Current length of the KEY FEEDBACK field. Because the feedback area is not cleared between calls, this value is the length of the current concatenated key in KEY FEEDBACK. Code Debug CICS ensures that only this amount of key feedback data displays.

KEY FEEDBACK

Concatenated key of the retrieved segment. The concatenated key consists of the keys of each of the segment’s parents and its own key. Keys are positioned left to right, starting with the key of the root segment and following the hierarchical path. DL/I does not normally clear this field. If DL/I cannot satisfy the call, it displays the key of the segment at the last level that was satisfied.

Because this field can extend beyond the limits of the display, use the LEFT and RIGHT scrolling commands to view data not on the display. To scroll this area, position the cursor on any line of the PCB information, and use the scrolling commands.