TBCLOSE—close and save a table

The TBCLOSE service terminates processing of the specified table and deletes the virtual storage copy, which is then no longer available for processing.

If the table was opened in WRITE mode, TBCLOSE copies the table from virtual storage to the table output library. In this case, the table output library must be allocated to a ddname of ISPTABL or defined by a LIBDEF service request before invoking this service. When storing a table in an output library, the user can give it a new name. The table name used in the output library must not be an alias name.

If the table was opened in NOWRITE mode, TBCLOSE simply deletes the virtual storage copy.

Table output can be directed to a table output library other than the default library specified on the table output ISPTABL DD statement. The library to be used must be allocated before table services receives control. Thus, an application can update a specific table library. This is particularly useful for applications that need to maintain a common set of tables containing their data.

A TBCLOSE request for a shared table causes the use count in the table for that logical screen to be decremented by one. If the use count for all logical screens is zero, the TBCLOSE service is performed. If the count is not zero, a TBSAVE service is performed. This leaves the table available for continued processing in any screen that still has a use count greater than zero.

Issuing a TBCLOSE with the LIBRARY parameter for a table is not related to closing the data set allocated to that ddname. However, if the LIBDEF service with the DATASET keyword is used to define the alternate library, the data set may be closed and freed by deleting the corresponding LIBDEF specification.

Command invocation format


                                 .-REPLCOPY-.   
>>-ISPEXEC--TBCLOSE--table-name--+----------+------------------->
                                 '-NEWCOPY--'   

>--+----------------+--+-----------------+---------------------->
   '-NAME(alt-name)-'  '-PAD(percentage)-'   

>--+------------------+----------------------------------------><
   '-LIBRARY(library)-'

Call invocation format


>>-CALL--ISPEXEC--(buf-len,--buffer);--------------------------><


>>-CALL--ISPLINK--('TBCLOSEb'--,--table-name-------------------->

     .-'REPLCOPY'-.                                     
>--,-+-'b'--------+--,-+-alt-name-+--,-+-percentage-+----------->
     '-'NEWCOPYb'-'    '-'b'------'    '-'b'--------'   

>--,-+-library-+-+-reserved--position-+-;----------------------><
     '-'b'-----' '-'b'----------------'

Parameters

table-name

Specifies the name of the table to be closed.

NEWCOPY

Specifies that the table is to be written at the end of the output library, regardless of whether an update in place would have been successful. This ensures that the original copy of the table is not destroyed before a replacement copy has been written successfully.

REPLCOPY

Specifies that the table is to be rewritten in place in the output library. If the existing member is smaller than the table that replaces it, or if a member of the same name does not exist in the library, the complete table is written at the end of the output library.

A comparison is made between the virtual storage size of the table and the external size in the table output library. If there is insufficient storage to write the table in place, it is written at the end of the table output library.

alt-name

Specifies an alternate name for the table. The table is stored in the output library with the alternate name. If another table already exists in the output library with that name, it is replaced. If the table being saved exists in the output library with the original name, that copy remains unchanged.

percentage

Specifies the percentage of padding space, based on the total size of the table. The padding is added to the total size of the table only when the table is written as a new copy. This parameter does not increase the table size when an update in place is performed.

This parameter must have an unsigned integer value. For a call, it must be a fullword fixed binary integer.

The default value for this parameter is zero.

Padding permits future updating in place, even when the table has expanded in size. Should the table expand beyond the padding space, the table is written at the end of the table output library instead of being updated in place.

library

Specifies the name of a DD statement or LIBDEF lib-type that defines the output library in which the table is to be closed. If specified, a generic (non-ISPF) ddname must be used. If this parameter is omitted, the default is ISPTABL.

buf-len

Specifies a fullword fixed binary integer containing the length of "buffer".

buffer

Specifies a buffer containing the name of the service and its parameters in the same form as they would appear in an ISPEXEC call for a command procedure.

Return codes

These return codes are possible:

0: Normal completion.
12: Table is not open.
16: Alternate table output library was not allocated.
20: Severe error.

Example

Close the table TELBOOK.

ISPEXEC TBCLOSE TELBOOK

Set the program variable BUFFER to contain:

TBCLOSE TELBOOK

Set program variable BUFLEN to the length of the variable BUFFER. Issue the command:

CALL ISPEXEC (BUFLEN, BUFFER);

or alternately

CALL ISPLINK ('TBCLOSE ','TELBOOK ');