tpf_filkw: File keyword

This function is used to request that the z/TPF system file format-1 global fields or records that can be keypointed.

You can update a keypoint record or a field name in a keypoint record. This function lets you restore the entry's storage protection to that of working storage.

Last updated

  • Changed in 2023 (information only; no code change).
  • Added for PUT00.

Format

 maketpf_env += system                                       
	#include <tpf/tpfglbl.h>                                    
	#include <tpf/c_globz.h>                                    
	void			tpf_filkw(enum t_filkw options, unsigned int number, 
									unsigned int tagname, ...);
options
Specifies the options associated with the keypoint request. Use one or more of the following defined terms. When specifying more than one term, use a + to separate the terms.
FILKW_RESTORE
Restore storage protection.
FILKW_NO_RESTORE
Does not restore storage protection.
FILKW_FIELD
One or more of the tagname parameters are field names.
Note: You can specify either FILKW_RESTORE or FILKW_NO_RESTORE, but not both.
number
Specifies the number of records or field names that follow. You can specify from 1–8.
tagname
Specifies the z/TPF global field, record, or keypoint record to be keypointed. This argument must be defined in header file c_globz.h or tpfglbl.h and must uniquely identify the field or record.
tagname...
Specifies that a maximum of eight tagname arguments can be specified.

Normal return

Void

Error return

Not Applicable

Programming considerations

  • If the parameter coded as tagname is not in one of the specified header files, the results of the function call cannot be predicted.
  • If the FILKW_FIELD option is specified, the field names must appear in a table in the FILKW macro definition and must equate to the corresponding keypoint record name.
  • If the FILKW_RESTORE option is specified, storage protection is restored to that of working storage. If FILKW_NO_RESTORE is specified, storage protection is not changed.
  • If keypointing is active, keypoints that are referenced using the tagname arguments will have been updated on file when the function is completed.
  • Use this function only for z/TPF format-1 globals. To keypoint z/TPF format-2 globals, use the tpf_glWrite and tpf_glClose functions.
  • In 1052 state, if this function is issued for a format-1 global field or record, the memory copy of the field or record is filed to DASD only when one of the following conditions occurs:
    • A subsequent GLOUC macro is issued without any parameters specified.
    • A subsequent GLOUC macro is issued with the ALL parameter specified.
    • The system is cycled above 1052 state.

Examples

The following example requests keypointing of keypointable global field _ns1ns. 
#include tpf/tpfglbl.h
#include tpf/c_globz.h
	int *ns1ns;
⋮
	ns1ns = (int *)glob(_ns1ns); 								/* Get access to _ns1ns         */
	tpf_glmod(TPF_GLOBAL1); 									    /* Turn off storage protection  */
	*ns1ns = *ns1ns+1 												       /* Update value.                */
	tpf_filkw ((enum t_filkw)(FILKW_RESTORE+FILKW_FIELD), _ns1ns);
																		                  	 /* Request keypoint and         */
																		                  	 /* restore storage protection   */
⋮