Selector value for Atom entries

The selector value for an Atom entry is any identifier that CICS or a service routine can use to locate the record in a file, temporary storage queue, or other resource that contains the data for the Atom entry. A suitable selector value is any identifier that is unique and always applies to a given record in the resource that holds the data for the Atom entries, such as an item number or unique key.

When CICS is issuing an Atom document as a response to a web client, CICS uses the selector values for the individual Atom entries to construct links directly to the Atom entries, and also as part of the generated Atom IDs for the entries. The web client can use the links to make requests for single Atom entries. The selector value from each link identifies the correct record in the resource that contains the data for the Atom entries. URLs for Atom feeds from CICS explains how a selector value is appended to a link.

When CICS is delivering Atom entries directly from a file or temporary storage queue, CICS identifies a suitable selector value depending on the type of resource. For a temporary storage queue, the selector value is the number that identifies the record in the temporary storage queue, which CICS assumes is a decimal number. For a file, the selector value is the key for the file, which must be unique. CICS assumes that the format of the selector value for each file type is as follows:
  • A decimal number for RRDS and VRRDS files.
  • A binary number for ESDS and extended ESDS files.
  • A character string for any other type of VSAM file.
If the key for your file is not in the format that CICS assumes, you can specify the correct format in the <cics:selector> element in the Atom configuration file.

When a service routine returns the data for Atom entries, you can choose what the selector value is. The selector value can be anything that your program can use to locate the correct record in your resource to provide the data for the Atom entry. For example, if the resource is a database, you might use the unique identifier that provides a key for the records. If the key is not a character string, you must specify in the <cics:selector> element in the Atom configuration file that you are using a hexadecimal selector value.

When a service routine returns an Atom entry from a feed or collection, you must use the ATMP_NEXTSEL parameter in the DFHATOMPARMS container to return a selector value for the next Atom entry that you have available in the feed. If the web client has requested a number of entries, CICS links to your program again using this selector value, so that your program can identify and return the next Atom entry that is held as a record in your resource. This process continues until CICS has enough entries for the feed, or until your program returns a null value to indicate that no further Atom entries are available from your resource.

When a service routine returns an Atom entry from a collection, you must use the ATMP_PREVSEL, ATMP_FIRSTSEL, and ATMP_LASTSEL parameters in the DFHATOMPARMS container to return selector values for the previous, first, and last Atom entries in the collection. CICS uses these values to construct <atom:link> elements containing links to other partial lists of entries in the collection. You may return these values for an Atom entry from a feed, if you think they would be useful to your web clients in order to retrieve other windows of Atom entries from the feed, but they are not required for a feed. The processing to produce a link using ATMP_PREVSEL increases response times, so only specify this value for a feed if your web clients are set up to use this form of navigation.

The identity of the first, previous, next, and last Atom entries in your feed or collection depends on the order in which you choose to return the Atom entries. Sequence for Atom entries explains how CICS determines the order in which to return Atom entries, and suggests the order in which a service routine can return Atom entries.



dfhtl_atom_selectorvalue.html | Timestamp icon Last updated: Sunday, 4 June 2017