Data Management Features
This chapter describes the database management features for managing files and records in OSC.
1. Overview
The following data management features are provided by OSC to help manage the data sets used by application programs.
2. File Control
Records in data files are managed as TSAM data sets, the OpenFrame equivalent to VSAM data sets in IBM mainframe. OSC application programs access TSAM data sets in the same way that CICS application programs access VSAM data sets; their functions are the same as well. With OSC application programs, users can search for, save, and delete the records stored in local files, as well as use function shipping to access records managed on remote application servers.
OSC application servers support three types of data sets as follows:
-
Key-sequenced data set (KSDS)
data sets in which each record is identified by a unique key.
-
Entry-sequenced data set (ESDS)
data sets in which each record is identified by an relative byte address (RBA).
-
Relative record data set (RRDS)
data sets in which each record is identified by an relative record number (RRN).
|
File Control Commands
The file control commands in OSC can be classified into four general categories:
-
Searching (browsing) records
Command Description Indicates the end of sequential search for a specific file.
Reads a specific record in a data set.
Reads the next record during a sequential search.
Reads the previous record during a sequential search.
Resets the sequential search location.
Specifies the first record of a sequential search.
-
Adding, deleting, and modifying records
Command Description Deletes a data set (only KSDS and RRDS are valid).
Modifies a record in the data set.
Adds a record to the data set.
-
Unlocking records
Command Description Unlocks a record that was locked with the READ UPDATE command.
-
File management
Command Description Retrieves information about a FILE resource definition.
Allows the properties of a data set to be modified.
File records are searched and read using the following two methods:
-
Direct access
Used to read a specific record. The READ command is used.
-
Sequential access
Used to read records sequentially. The READNEXT or READPREV commands are used to read records, and the STARTBR, RESETBR and ENDBR commands to specify the starting point, reset and end records respectively.
2.1. DELETE
Deletes a record. Records can only be deleted from the KSDS and RRDS type data sets. To specify the record to delete from a data set, either use the token value returned by the UPDATE option of a search or read command, or use the RIDFLD value.
-
Syntax
EXEC CICS DELETE [option …] END-EXEC.
-
Options
Option Description FILE
Specifies the name of the file whose records to be deleted.
KEYLENGTH
Specifies the key length. (valid only for KSDS)
GENERIC
Indicates that the value expressed in KEYLENGTH is a GENERIC key.
NUMREC
Returns the number of deleted records.
RBA
Indicates that the value specified in the RIDFLD option is an RBA.
RIDFLD
Specifies the record ID of the field to be deleted.
-
KSDS: uses a key to identify records.
-
RRDS: uses a record relative number (RRN) value to identify records.
RRN
Indicates that the value specified in the RIDFLD option is an RRN.
SYSID
Specifies the SYSID of the remote system.
TOKEN
Specifies the token value received from the UPDATE option of READ, READNEXT, or READPREV.
-
2.2. ENDBR
Indicates the end of sequential search for a specific file.
-
Syntax
EXEC CICS ENDBR [option …] END-EXEC.
-
Options
Option Description FILE
Specifies the name of the file to be read.
REQID
Specifies the ID that requests sequential search through the STARTBR command.
SYSID
Specifies the SYSID of a remote system.
2.3. INQUIRE FILE
Retrieves information about a FILE resource definition.
-
Syntax
EXEC CICS INQUIRE FILE [option …] END-EXEC.
-
Options
Option Description ADD
Returns an indicator that shows whether a new record can be added to the file.
BROWSE
Returns an indicator that shows whether the file can be browsed.
DELETE
Returns an indicator that shows whether a record can be removed from the file.
DSNAME
Returns a 44-character name of a VSAM object associated with the FILE definition.
ENABLESTATUS
Returns an indicator that shows whether the file is accessible to an application program or not.
END
Ends browsing.
FILE
Specifies an 8-character name of the file.
KEYLENGTH
Returns the length of the record key for a file associated with the VSAM KSDS or with a coupling facility data table (CFDT).
MAXNUMRECS
Returns the maximum number of records that can be saved in the data table of the file.
NEXT
Repeats the INQUIRE command. Only one resource definition is returned.
OPENSTATUS
Returns an indicator that shows if the file is open, closed, or being processed.
READ
Returns an indicator that shows whether a record can be read from the file.
RECORDFORMAT
Returns an indicator of the record type of the file.
RECORDSIZE
Returns the actual size of a fixed-length record or the maximum size of a variable-length record.
REMOTENAME
Returns an 8-character name of the OSC region specified in the REMOTESYSTEM option.
REMOTESYSTEM
Returns a 4-character name of the OSC region.
START
Starts browsing.
UPDATE
Returns an indicator that shows whether the file can be updated.
The following options are not supported: ACCESSMETHOD, BASEDSNAME, BLOCKFORMAT, BLOCKKEYLEN, BLOCKSIZE, CFDTPOOL, CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSRID, DEFINESOURCE, DEFINETIME, DISPOSITION, EMPTYSTATUS, EXCLUSIVE, FWDRECSTATUS, INSTALLAGENT, INSTALLTIME, INSTALLUSRID, JOURNALNUM, KEYPOSITION, LOADTYPE, LSRPOOLNUM, OBJECT, RBATYPE, READINTEG, RECOVSTATUS, RELTYPE, REMOTETABLE, RLSACCESS, STRINGS, TABLE, TABLENAME, TYPE and UPDATEMODEL.
2.4. READ
Reads a specific record in a data set.
-
Syntax
EXEC CICS READ [option …] END-EXEC.
-
Options
Option Description EQUAL
Retrieves only the records with record IDs that match the value in RIDFLD.
FILE
Specifies the name of the data set to be read.
GENERIC
Indicates that the value expressed in KEYLENGTH is a GENERIC key.
GTEQ
Retrieves only the records with record IDs that are greater than or equal to the value in RIDFLD.
INTO
Specifies the location to store the data to be read.
KEYLENGTH
Specifies the key length. (for KSDS only)
LENGTH
Specifies the length of the data in the record buffer (specified in INTO).
The option must be specified when the SYSID option is specified. If the file exists on a remote system and the LENGTH option is not specified, the RECORDSIZE value of the FILE resource definition is read.
NOSUSPEND
Indicates that a request does not wait if a record is locked by DEADLOCK or is under an active lock by VSAM.
RBA
Indicates that the value specified in the RIDFLD option is an RBA.
RIDFLD
Specifies the record ID of the field to be read.
-
KSDS: uses a key.
-
ESDS: uses an RBA value.
-
RRDS: uses an RRN value.
RRN
Indicates that the value specified in the RIDFLD option is an RRN.
SET
Specifies a pointer reference to contain the address of the data to be read.
SYSID
Specifies the SYSID of the remote system.
TOKEN
Returns the unique identifier used for READ UPDATE.
UPDATE
Locks the record against modification or deletion.
Only parsing is supported for DEBKEY and DEBREC.
-
2.5. READNEXT
Reads the next record during a sequential search. The STARTBR command must be used to set the starting location of the search.
-
Syntax
EXEC CICS READNEXT [option …] END-EXEC.
-
Options
Option Description FILE
Specifies the name of the file to be read.
INTO
Specifies the location to store the data to be read.
KEYLENGTH
Specifies the key length (for KSDS only).
LENGTH
Specifies the length of the data in the record buffer (specified in INTO).
The option must be specified when the SYSID option is specified. If the file exists on a remote system and the LENGTH option is not specified, the RECORDSIZE value of the FILE resource definition is read.
NOSUSPEND
Indicates that a request does not wait if a record is locked by DEADLOCK or is under an active lock by VSAM.
RIDFLD
Specifies the record ID of the field to be read.
-
KSDS: uses a key.
-
ESDS: uses an RBA value.
-
RRDS: uses an RRN value.
RBA
Indicates that the value specified in the RIDFLD option is an RBA.
REQID
Specifies the ID that requests sequential search through the STARTBR command.
RRN
Indicates that the value specified in the RIDFLD option is an RRN.
SET
Specifies a pointer reference to contain the address of the data to be read.
SYSID
Specifies the SYSID of the remote system.
TOKEN
Returns the unique identifier used for READ UPDATE.
UPDATE
Locks the record against modification or deletion.
-
2.6. READPREV
Reads the previous record during a sequential search. The STARTBR command must be used to set the starting location of the search.
-
Syntax
EXEC CICS READPREV [option …] END-EXEC.
-
Options
Option Description FILE
Specifies the name of the file to be read.
KEYLENGTH
Specifies the key length (for KSDS only).
INTO
Specifies the location to store the data to be read.
LENGTH
Specifies the length of the data in the record buffer (specified in INTO).
The option must be specified when the SYSID option is specified. If the file exists on a remote system and the LENGTH option is not specified, the RECORDSIZE value of the FILE resource definition is read.
NOSUSPEND
Indicates that a request does not wait if a record is locked by DEADLOCK or is under an active lock by VSAM.
RBA
Indicates that the value specified in the RIDFLD option is an RBA.
REQID
Specifies the ID that requests sequential search through the STARTBR command.
RIDFLD
Specifies the record ID of the field to be read.
-
KSDS: uses a key
-
ESDS: uses an RRN value
-
RRDS: uses an RRN value
RRN
Indicates that the value specified in the RIDFLD option is an RRN.
SET
Specifies a pointer reference to contain the address of the data to be read.
SYSID
Specifies the SYSID of the remote system.
TOKEN
Returns the unique identifier used for READPREV UPDATE.
UPDATE
Locks the record against modification or deletion.
-
2.7. RESETBR
Changes the sequential search properties set by a STARTBR command, or to move the browser cursor position during a sequential search.
-
Syntax
EXEC CICS RESETBR [option …] END-EXEC.
-
Options
Option Description EQUAL
Indicates that the key value of the new search location must be equal to the value specified in RIDFLD.
FILE
Specifies the name of the file.
GENERIC
Indicates that the value expressed in KEYLENGTH is a GENERIC key.
GTEQ
Indicates that the key value of the new search location must be equal to or greater than the value specified in RIDFLD.
KEYLENGTH
Specifies the key length (for KSDS only).
RBA
Indicates that the value specified in the RIDFLD option is an RBA.
REQID
Specifies the ID that requests sequential search through the STARTBR command.
RIDFLD
Specifies the record ID of the field to be set.
-
KSDS: uses a key
-
ESDS: uses an RRN value
-
RRDS: uses an RRN value
RRN
Indicates that the value specified in the RIDFLD option is an RRN.
SYSID
Specifies the SYSID of the remote system.
-
2.8. REWRITE
Modifies an existing record in a data set. Records retrieved with the UPDATE option of READ, READNEXT, or READPREV can be modified with this command.
-
Syntax
EXEC CICS REWRITE [option …] END-EXEC.
-
Options
Option Description FILE
Specifies the name of the file to rewrite the record.
FROM
Specifies the data of a record to write.
LENGTH
Specifies the length of a record to write.
The option must be specified when the SYSID option is specified. If the file exists on a remote system and the LENGTH option is not specified, the RECORDSIZE value of the FILE resource definition is read.
NOSUSPEND
Indicates that a request does not wait if a record is locked by DEADLOCK or is under an active lock by VSAM.
SYSID
Specifies the SYSID of a remote system.
TOKEN
Returns a token value received by the UPDATE option of the READ, READNEXT, and READPREV commands. .
2.9. SET FILE
Modifies file properties. Files can be set to allow or disallow modification, searching, deletion, and more.
-
Syntax
EXEC CICS SET FILE [option …] END-EXEC.
-
Options
Option Description ADD
Specifies whether or not records can be added to the file.
ADDABLE
Indicates that records can be added to the file.
BROWSABLE
Indicates that the file can be read.
BROWSE
Specifies whether or not the file can be read.
CFTABLE
Indicates that the file name refers to a coupling facility data table (CFDT).
CICSTABLE
Indicates that the file name represents a data table maintained in OSC.
CLOSED
Closes the file.
CONSISTENT
Sets the level of read integrity to CONSISTENT.
DELETE
Specifies whether records can be deleted from the file.
DELETABLE
Indicates that records can be deleted from the file.
DISABLED
Sets the file status to DISABLED.
DSNAME
Specifies the name of a data set used for the file.
EMPTYREQ
Sets the data set, if defined as reusable, to be opened as empty when the file that references the data set is opened in non-RLS mode.
EXCTL
Indicates that records in this file are under exclusive control when they are being read for an update.
ENABLESTATUS
Sets the file status either to ENABLED or DISABLED.
ENABLED
Sets the file status to ENABLED.
FILE
Specifies the name of the file whose status or attributes to change.
FORCE
Abnormally terminates all tasks that use the file, immediately sets the status of the file to DISABLED or CLOSED, and returns the control to an application program.
KEYLENGTH
Specifies a fullword binary value to indicate the key length of a records in a coupling facility data table. The value can be 1 to 16 bytes. To remove the key length, set this option to KEYLENGTH (0).
LOAD
Indicates that a coupling facility data table (CFDT) is loaded before using a source data set.
NOLOAD
Indicates that a coupling facility data table (CFDT) is not loaded before using a source data set.
MAXNUMRECS
Specifies a fullword binary value to indicate the maximum number of records in a data table. The value ranges from 1 to 99999999. To remove the maximum limit, set this option to MAXNUMRECS (0).
NOEMPTYREQ
Sets the data set, if defined as reusable, not to be empty when the file that references the data set is opened.
NOEXCTL
Indicates that records on this file are not under exclusive control when they are being read for an update.
NOTADDABLE
Indicates that records cannot be added to the file.
NOTBROWSABLE
Indicates that the file cannot be read.
NOTDELETABLE
Indicates that records cannot be deleted from the file.
NOTREADABLE
Indicates that the file record cannot be read.
NOTRLS
Indicates that the file is opened in LSR or NSR mode when it is next opened.
NOTTABLE
Indicates that the file name does not represent the data table.
NOTUPDATABLE
Indicates that the file record cannot be updated.
NOWAIT
Same as WAIT except that OSC returns control to the application as soon as the SET request is queued.
OLD
Replaces DISPOSITION with OLD if the file is open during execution of the SET FILE DISPOSITION command.
OPENSTATUS
Opens or closes the file.
OPEN
Opens the file.
READ
Specifies whether records in the file are readable.
RECORDSIZE
Specifies a fullword binary value to indicate the maximum size of a record in a coupling facility data table. The value ranges from 1 to 32767. To remove the existing value, set this option to 0.
RLS
Indicates that the file is opened in RLS access mode the next time it is opened.
READABLE
Indicates that the file record can be read.
REPEATABLE
Sets the level of read integrity to repeatable.
RLSACCESS
Indicates whether to access the file in RLS mode. To enable an RLS access or a non-RLS access, close the file and set the status to DISABLED.
SHARE
Replaces DISPOSITION with SHARE if the file is open during execution of the SET FILE DISPOSITION command.
UNCOMMITTED
Indicates that read integrity is not required.
UPDATE
Specifies whether records in the file can be updated.
WAIT
Indicates that a request waits until all activity regarding the file is suspended before setting the file to DISABLED or CLOSED. WAIT is the default value. (Default value)
-
The following commands are not supported: BUSY, data set, CFDTPOOL, DISPOSITION, OBJECTNAME, EMPTYSTATUS, EXCLUSIVE, LOADTYPE, LSRPOOLNUM, READINTEG, READINTEG, STRINGS, TABLE and TABLENAME.
-
Only parsing is supported for CONTENTION, END, LOCKING, NEXT, START,UPDATABLE, and UPDATEMODEL.
-
The following BATCH MTPBATCH command can be used to change STATUS and PERMISSION instead of SET FILE. The following are also available: CLOS <file_name>, OPEN <file_name>.
CEMT SET FI<file_name> DISABLED CLOSED | ENABLE OPEN CEMT SET FI<file_name> [READ | NOREAD] [UPDATE | NOUPDATE] [ADDABLE | NOADDABLE] [BROWSE | NOBROWSE] [DELETE | NODELETE]
-
2.10. STARTBR
Creates a browser cursor that will be used for sequential searching. The cursor points to the starting position of the sequential search.
-
Syntax
EXEC CICS STARTBR [option …] END-EXEC.
-
Options
Option Description EQUAL
Indicates that only records with record IDs that match the value in RIDFLD will be read.
FILE
Specifies the name of the file to search.
GENERIC
Indicates that the value expressed in KEYLENGTH is a GENERIC key.
GTEQ
Points to the starting position of the sequential search for the records with record IDs that are greater than or equal to the value in RIDFLD.
KEYLENGTH
Specifies the key length (KSDS only).
RIDFLD
Specifies the record ID of the field to be read.
-
KSDS: uses a key.
-
ESDS: uses an RBA value.
-
RRDS: uses an RRN value.
RBA
Indicates that the value specified in the RIDFLD option is an RBA.
REQID
Specifies the request ID for the sequential search.
RRN
Indicates that the value specified in the RIDFLD option is an RRN.
SYSID
Specifies the SYSID of the remote system.
Only parsing is supported for DEBKEY and DEBREC.
-
2.11. UNLOCK
Unlocks a record that was previously locked by the UPDATE option of READ, READNEXT or READPREV. If an UNLOCK command is not given, a locked record will automatically be unlocked by a SYNCPOINT command or when the task ends.
-
Syntax
EXEC CICS UNLOCK [option …] END-EXEC.
-
Options
Option Description FILE
Specifies the file location of the record to be unlocked.
TOKEN
Specifies the token value received from the UPDATE option of READ, READNEXT or READPREV.
SYSID
Specifies the SYSID of the remote system.
2.12. WRITE
Writes a new record to a data set.
-
Syntax
EXEC CICS WRITE [option …] END-EXEC.
-
Options
Option Description FILE
Specifies the file to which to write records.
FROM
Specifies the data area containing the data that will be written to the data set.
KEYLENGTH
Specifies the key length (KSDS only).
LENGTH
Specifies the length of the record to be written.
The option must be specified when the SYSID option is specified. If the file exists on a remote system and the LENGTH option is not specified, the RECORDSIZE value of the FILE resource definition is read.
MASSINSERT
Indicates that the record will be written as part of a MASSINSERT operation.
NOSUSPEND
Indicates that a request does not wait if a record is locked by DEADLOCK or is under an active lock by VSAM.
RBA
Indicates that the value specified in the RIDFLD option is an RBA.
RIDFLD
Specifies the record ID of the field to be written.
-
KSDS: uses a key
-
ESDS: uses an RRN value
-
RRDS: uses an RRN value
RRN
Indicates that the value specified in the RIDFLD option is an RRN.
SYSID
Specifies the SYSID of the remote system.
-
3. Named Counter Server
The named counter server (hereafter NCS) monitors the values of named counter variables. Whenever a user requests a value from a counter, the counter value is increased by one. The NCS provides functions to set the minimum and maximum server values and the incremental value of the counter, reset a counter, and delete a counter.
The OSC application server supports two kinds of counters, COUNTER and DCOUNTER. COUNTER stores values as a 4 byte binary integer (fullword signed binary value), while DCOUNTER stores values as an 8 byte binary positive value (doubleword unsigned binary value). COUNTER and DCOUNTER are used in the same manner, but are accessed by different commands.
Named Counter Access Commands
The following is a list of counter access commands, which allow application programs to access NCS. For more information about each command, refer to the respective section.
Command | Description |
---|---|
Creates a named counter. |
|
Deletes a named counter. |
|
Retrieves the next value from a named counter. |
|
Retrieves information about a named counter. |
|
Rewinds a named counter that has reached its maximum value. |
|
Updates the current value of a named counter. |
3.1. DEFINE COUNTER|DCOUNTER
Creates a named counter.
-
Syntax
EXEC CICS DEFINE COUNTER|DCOUNTER [option …] END-EXEC.
-
Options
Option Description COUNTER|DCOUNTER
Specifies the counter name.
MAXIMUM
Specifies the maximum value of the counter.
MINIMUM
Specifies the minimum value of the counter.
POOL
Specifies the name of the POOL where the counter will be located.
VALUE
Specifies the initial value of the counter.
3.2. DELETE COUNTER|DCOUNTER
Deletes a named counter.
-
Syntax
EXEC CICS DELETE COUNTER|DCOUNTER [option …] END-EXEC.
-
Options
Option Description COUNTER|DCOUNTER
Specifies the name of the counter to delete.
POOL
Specifies the name of the POOL where the counter is located.
3.3. GET COUNTER|DCOUNTER
Retrieves the next value from a named counter.
-
Syntax
EXEC CICS GET COUNTER|DCOUNTER [option …] END-EXEC.
-
Options
Option Description COMPAREMAX
Retrieves a counter value only if it is smaller than or equal to the specified value.
COMPAREMIN
Retrieves a counter value only if it is greater than or equal to the specified value.
COUNTER|DCOUNTER
Specifies the counter from which a value will be retrieved.
INCREMENT
Increments the counter by the specified number after retrieving a value.
POOL
Specifies the name of the POOL where the counter is located.
REDUCE
Reduces the counter value.
VALUE
Specifies a data area where the retrieved value will be saved.
WRAP
Automatically rewinds the counter if the maximum value is reached.
3.4. QUERY COUNTER|DCOUNTER
Retrieves information about named counters.
-
Syntax
EXEC CICS QUERY COUNTER|DCOUNTER [option …] END-EXEC.
-
Options
Option Description COUNTER/DCOUNTER
Specifies the name of the counter to query.
MAXIMUM
Returns the maximum value of the counter.
MINIMUM
Returns the minimum value of the counter.
POOL
Specifies the name of the POOL where the counter is located.
VALUE
Returns the current value of the counter.
3.5. REWIND COUNTER|DCOUNTER
Rewinds a named counter that has reached its maximum value.
-
Syntax
EXEC CICS REWIND COUNTER|DCOUNTER [option …] END-EXEC.
-
Options
Option Description COUNTER|DCOUNTER
Specifies the name of the counter to rewind.
INCREMENT
Specifies the incremental value to be used to check whether the counter reaches the maximum value.
POOL
Specifies the POOL name where counter is located.
3.6. UPDATE COUNTER|DCOUNTER
Updates the current value of a named counter.
-
Syntax
EXEC CICS UPDATE COUNTER|DCOUNTER [option …] END-EXEC.
-
Options
Option Description COMPAREMAX
Updates the counter only if the update value is smaller than or equal to the specified value.
COMPAREMIN
Updates the counter only if the update value is greater than or equal to the specified value.
COUNTER|DCOUNTER
Specifies the name of the counter to update.
POOL
Specifies the name of the POOL where the counter is located.
VALUE
Specifies a new value.
4. DB2 Session Inquiry
Users can inquire on resources and settings required when they establish a session with DB2 as a database that communicates with the OSC server.
DB2CONN Command
The following is a command to inquire DB2 session information. Applications can retrieve information about a DB2 session through the following command. For more information about the command, refer to the respective section.
Command | Description |
---|---|
Inquires session information between OSC and DB2. |
4.1. INQUIRE DB2CONN
Inquires DB2 session information.
-
Syntax
EXEC CICS INQUIRE DB2CONN [option …] END-EXEC.
-
Option
Option Description DB2ID
Retrieves the VALUE of the DB2ID key in the DB2CONN section, from the osc.{servername} subject under OpenFrame Configuration.
For more information about the osc.{servername} subject, refer to OpenFrame Configuration Guide.