QUERY command processing

GIMAPI checks to see if the SMPCSI DDNAME is already allocated. If it is, GIMAPI notes the data set name. GIMAPI then determines if the caller expects GIMAPI to allocate the global CSI data set. The caller indicates this by setting the csilen parameter to zero. The data set name previously noted is used so a shared enqueue can be done. The enqueue is to protect GIMAPI processing from updates by any other SMP/E processing that might be going on at the same time.

If the csilen parameter is not zero, GIMAPI verifies that the csi parameter provided is a valid CSI data set name.

If the SMPCSI DDNAME has already been allocated, the data set name of the allocation must be the same as the CSI parameter value. If they match, GIMAPI treats it as if the calling program already did the allocation. The data set is not allocated again (and is not deallocated at the end of the command).

If the CSI data set must be allocated, GIMAPI dynamically allocates the data set with DISP=SHR.

GIMAPI continues by validating the rest of the required QUERY parameters that it has received. Syntax checking is done for each QUERY parameter received. If GIMAPI encounters an error, it stops syntax checking for that parameter list and moves on to begin syntax checking for the next QUERY parameter. If any errors are found, the QUERY command terminates after syntax checking is done. The command continues if warnings are the highest severity found.

GIMAPI enforces these syntax rules:

When multiple values are specified on the zone, entry or subentry parameters, they must be appropriately separated by commas or spaces.
When an asterisk (*) is used on the zone, entry or subentry parameters, no other values can be specified.
Entry types entered on the entry parameter must be a valid CSI entry type.
A specific value can be specified only once on the zone, entry or subentry parameters.
A condition using the >, >=, < or <= operator with a subentry type that is not a date or time field is not allowed.
There are a set of subentry types that are not allowed to be used in conditions on the filter parameter. See topic Filter parameter syntax for the list.
A null value for a subentry may be specified by using two single quotation marks with no other characters or blanks between them (''). A null value may be used with the "not equal" (!=) operator to find all entries that have some value — for example, PATH!=''.
A date fixed value must use the format 'yyddd'. GIMAPI checks the characters entered to make sure they are all numeric.
A time fixed value must use the format 'hh:mm:ss', where hh is a two-digit decimal number in the range 00 through 23, and mm and ss are both two-digit decimal numbers in the range 00 through 59. (That is, in 24-hour clock format.)
A null value can be used with date and time fields with the = and != operators to check if the values have been set or not.
A closing quotation mark "'" must be found by the end of the filter parameter.
All parentheses must be closed before the filter parameter string ends.
When any other syntax errors are found in the filter parameter, GIMAPI issues a general syntax error message specifying the character position with the error.

Once the syntax is checked and zones other than the GLOBAL zone are specified, specific zone names are checked to see if they are ZONESETs. If so, the ZONESET name is removed from the list of zones passed by the caller and replaced with the zone names from the ZONESET. An attempt is then made to read the ZONEINDEX for each of the zones to be processed to see if any other CSI data sets need to be dynamically allocated. If one of the zones specified is not a ZONESET and cannot be found in the ZONEINDEX, the QUERY command terminates.

If any of the target zones or DLIB zones are contained in separate CSI data sets than the global CSI, those data sets must be allocated. The command first determines if they are already allocated by the calling routine. If so, that allocation is used and the data sets are not deallocated later. If not, the data sets are allocated with DISP=SHR. In either case, a shared enqueue is done.

The command now attempts to process the query. The requested entries are read from the CSI and compared with the filter. If there is a match, the requested subentries and their values are attached to the output storage. This is a set of data structures linked together, with storage being allocated for each structure used.

Once all entries are processed, any CSI data sets that were dynamically allocated are dequeued and deallocated.

Note: Any successful allocations and enqueues are undone, even if errors are found. The data sets are always freed when the program ends.

If the query requested from the calling program did not result in any data being returned, the command output parameter is set to zero.