9.198 SPACE_OPERATION

Note: Built-In Function Rules     Usage Options

Requests a miscellaneous space object operation.

Arguments

No

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

1

A

R

Space Name

1

256

 

 

2

A

R

Requested Operation

1

256

 

 

3-20

X

O

Fields that specify additional operation dependent arguments.    

1

Unlimited

0

Unlimited

 

Return Values

No

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

1

A

O

Standard Return Code

"ER" = Request failed. Messages issued will indicate more about the cause of the failure. 

Other return code values depend upon the operation requested.  See the description of each operation for more details. 

2

2

 

 

2-20

X

O

Fields that specify additional operation dependent return values.

1

Unlimited

0

Unlimited

 

The CheckExistence Operation

The CheckExistence operation can be used to check for the existence of a space object within the current operating system process (or job).
In the following example, it checks for the existence of a space named TestSpace:

Use Builtin(SPACE_OPERATION) With_Args('TestSpace' CHECKEXISTENCE) To_Get(#SPACERC)

The return code is only ever returned as "OK" (space object exists) or "NR" (space object does not exist) by valid CheckExistence requests.

The SetCursor Operation

The SetCursor operation can be used to set the cursor for ALL subsequent invocations of the SELECT_IN_SPACE or SELECTNEXT_IN_SPACE BIFs. It is not specific to the space object. If the cursor is set to 2, all subsequent select BIFs for any space object will use cursor 2 until it is changed to something different. The default cursor is 1, and up to 4 cursors can be specified for each space object. The only checking performed is to ensure that the cursor number is between 1 and 4.

For example ...

Use Builtin(SPACE_OPERATION) With_Args('TestSpace' SETCURSOR 2) To_Get(#SPACERC)

The return code is only ever returned as "OK" (space object exists) or "ER" (cursor number invalid) by valid SetCursor requests.

This operation permits SELECT_IN_SPACE requests for the same space object to be nested. To be used effectively, the SetCursor operation should be called just before using the SELECT_IN_SPACE or SELECTNEXT_IN_SPACE BIFs to ensure that the correct cursor is being used. This is typical of the use of the SetCursor operation to ensure that no unwanted side-effects occur by using the wrong cursor because, for example, the LEAVE command was issued from the inner loop:

Use Builtin(SPACE_OPERATION) With_Args(#AR_SPACE SetCursor 1) To_Get(#SPACERC)

Use Builtin(SELECT_IN_SPACE) With_Args(#AR_SPACE) To_Get(#SPACERC #XG_AR)

Dowhile Cond(*SPACEOK)

   Use Builtin(SPACE_OPERATION) With_Args(#AR_SPACE SetCursor 2) To_Get(#SPACERC)

   * Note the use of a different set of fields to hold the data - #XG_AR2

   Use Builtin(SELECT_IN_SPACE) With_Args(#AR_SPACE) To_Get(#SPACERC #XG_AR2)

   Dowhile Cond(*SPACEOK)

      * Do something with the data here

      Use Builtin(SPACE_OPERATION) With_Args(#AR_SPACE SetCursor 2) To_Get(#SPACERC)

      Use Builtin(SELECTNEXT_IN_SPACE) With_Args(#AR_SPACE) To_Get(#SPACERC #XG_AR2)

   Endwhile

   Use Builtin(SPACE_OPERATION) With_Args(#AR_SPACE SetCursor 1) To_Get(#SPACERC)

   Use Builtin(SELECTNEXT_IN_SPACE) With_Args(#AR_SPACE) To_Get(#SPACERC #XG_AR)

Endwhile

* Set the cursor back to the default for any further SELECT... BIF calls.

Use Builtin(SPACE_OPERATION) With_Args(#AR_SPACE SetCursor 1) To_Get(#SPACERC)