SFS_DIRECTORY

In addition to the QUERY_DIRECTORY_ENTRY verb, there is the SFS_DIRECTORY verb that allows the local directory cache on a network node to be safely stored and can be later accessed if the node is restarted. The restore flag is used to indicate whether information is being stored (AP_NO) or accessed (AP_YES).

When the restore flag is set to AP_YES, SFS_DIRECTORY allows the directory database to be rebuilt using directory_entry_summary overlays. To obtain information about a specific network node or to obtain the list information in several chunks, the resource_name and resource_type fields should be set.

Otherwise (if the list_options field is set to AP_FIRST_IN_LIST), this field will be ignored. See Querying the Node for background on how the list formats are used.

Resource information on the cached entries and their parents is returned in the following order:

1st Network Node
                        1st LU located at Network Node
                        2nd LU locate at Network Node
                        ...
                        nth LU located at Network Node
           1st End Node served by this Network Node
                        1st LU located at End Node(1)
                        2nd LU located at End Node(1)
                        ...
                        nth LU located at End Node(1)
            ...
            nth End Node served by this Network Node
                        1st LU located at End Node(n)
                        2nd LU located at End Node(n)
                        ...
2nd Network Node
           ...etc..    

VCB Structure

typedef struct sfs_directory
{
        unsigned short  opcode;              /* verb operation code         */
        unsigned char   reserv2;             /* reserved                    */
        unsigned char   format;              /* format                      */
        unsigned short  primary_rc;          /* primary return code         */
        unsigned long   secondary_rc;        /* secondary return code       */
        unsigned char   *buf_ptr;            /* pointer to buffer           */
        unsigned long   buf_size;            /* buffer size                 */
        unsigned long   total_buf_size;      /* total buffer size required  */
        unsigned short  num_entries;         /* number of entries           */
        unsigned short  total_num_entries;   /* total number of entries     */
        unsigned char   list_options;        /* listing options             */
        unsigned char   restore;             /* store or restore flag       */
        unsigned char   resource_name[17];   /* network qualified res name  */
        unsigned char   reserv3;             /* reserved                    */
        unsigned short  resource_type;       /* Resource type               */
       } SFS_DIRECTORY;
typedef struct directory_entry_summary
{
        unsigned short  overlay_size;        /* size of this entry          */
        unsigned char   resource_name[17];   /* network qualified res name  */
        unsigned char   reserve1;            /* reserved                    */
        unsigned short  resource_type;       /* Resource type               */
        unsigned short  real_owning_cp_type; /* real owning CP type         */
        unsigned char   real_owning_cp_name[17];
                                             /* real owning CP name         */
        unsigned char   description[RD_LEN]; /* resource description        */
} DIRECTORY_ENTRY_SUMMARY;

Supplied Parameters

Supplied Parameters when restore = AP_NO

The application supplies the following parameters:
opcode
AP_SFS_DIRECTORY
format
Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.
buf_ptr
Pointer to a buffer where list information can be written. The application can append data to the end of the VCB, in which case buf_ptr must be set to NULL.
buf_size
Size of buffer supplied. The data returned will not exceed this size.
num_entries
Maximum number of entries to return. The number of entries will not exceed this value. A value of zero means no limit.
list_options
This indicates what should be returned in the list information. The resource_name and resource_type specified (see the following parameters, resource_name and resource_type) represents an index value that is used to specify the starting point of the actual information to be returned.
AP_FIRST_IN_LIST
The index value is ignored, and the returned list starts from the first entry in the list.
AP_LIST_FROM_NEXT
The returned list starts from the next entry in the list after the one specified by the supplied index value.
restore
Flag indicating whether the information should be restored (AP_YES) or stored (AP_NO). In this case, it is set to AP_NO.
resource_name
Network qualified resource name. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composes of two type-A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded spaces.) This field is ignored if list_options is set to AP_FIRST_IN_LIST.
resource_type
Resource type. See one of the following:

AP_NNCP_RESOURCE
AP_ENCP_RESOURCE
AP_LU_RESOURCE

This field is ignored if list_options is set to AP_FIRST_IN_LIST.

Returned Parameters

If the verb executes successfully, the Program returns the following parameters:
primary_rc
AP_OK
buf_size
Length of the information returned in the buffer.
total_buf_size
Returned value indicating the size of buffer that would have been required to return all the list information requested. This can be higher than buf_size.
total_num_entries
Total number of entries that could have been returned. This can be higher than num_entries.
num_entries
The number of entries actually returned.
directory_entry_summary.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
directory_entry_summary.resource_name
Network qualified resource name. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composes of two type-A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded spaces.) This field is ignored if list_options is set to AP_FIRST_IN_LIST.
directory_entry_summary.resource_type
Resource type. See one of the following:

AP_NNCP_RESOURCE
AP_ENCP_RESOURCE
AP_LU_RESOURCE

If the verb does not execute because of a parameter error, the Program returns the following parameters:
primary_rc
AP_PARAMETER_CHECK
secondary_rc
AP_INVALID_RES_NAME

AP_INVALID_LIST_OPTION
AP_INVALID_RES_TYPE

directory_entry_summary.real_owning_cp_type
NN and BrNN only: Real owning CP type. This can be one of the following:
AP_NONE
The real owning CP is a parent resource.
AP_ENCP_RESOURCE
The real owning CP is not the parent resource and is an EN.

Other node types: This field is set to AP_NONE.

directory_entry_summary.real_owning_cp_name
NN and BrNN only: Fully qualified real owning CP name. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composed of two type A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded spaces.)

If the real owning CP is the parent, this field is set to binary zeroes.

If the real owning CP is not the parent, then this field is set to the name of the real owning CP.

The real owning CP is not the parent in the directory of the NNS of a BrNN if the resource is owned by an EN in the domain of the BrNN. In this case, the real owning CP is the EN, but the parent is the BrNN.

Other node types: This field is set to binary zeroes.

Supplied Parameters

Supplied Parameters when restore = AP_YES

The application supplies the following parameters:
opcode
AP_SFS_DIRECTORY
format
Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.
buf_ptr
Pointer to a buffer where list information can be written. The application can append data to the end of the VCB, in which case buf_ptr must be set to NULL.
buf_size
Size of the buffer supplied.
restore
Flag indicating whether the information should be restored (AP_YES) or stored (AP_NO). In this case, it is set to AP_NO.
resource_name
Network qualified resource name. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composes of two type-A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded spaces.) If the application is restoring the first chunk of the directory, then this should be set to all zeros. Otherwise, the application should set this to the resource name of the last item in the previous chunk.
resource_type
Resource type. See one of the following:

AP_NNCP_RESOURCE
AP_ENCP_RESOURCE
AP_LU_RESOURCE

This field should be set to zero if the application is restoring the first chunk of the directory.

directory_entry_summary.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any). This must be the same as the overlay_size value returned when restore is set to AP_NO.
directory_entry_summary.resource_name
Network qualified resource name. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composes of two type-A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded spaces.)
directory_entry_summary.resource_type
Resource type. See one of the following:

AP_NNCP_RESOURCE
AP_ENCP_RESOURCE
AP_LU_RESOURCE

directory_entry_summary.real_owning_cp_type
NN and BrNN only: Real owning CP type. This can be one of the following:
AP_NONE
The real owning CP is a parent resource.
AP_ENCP_RESOURCE
The real owning CP is not the parent resource and is an EN.

Other node types: This field is set to AP_NONE.

directory_entry_summary.real_owning_cp_name
NN and BrNN only: Fully qualified real owning CP name. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composed of two type A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded spaces.)

If the real owning CP is the parent, this field is set to binary zeroes.

If the real owning CP is not the parent, then this field is set to the name of the real owning CP.

The real owning CP is not the parent in the directory of the NNS of a BrNN if the resource is owned by an EN in the domain of the BrNN. In this case, the real owning CP is the EN, but the parent is the BrNN.

Other node types: This field is set to binary zeroes.

Returned Parameters

If the verb executes successfully, the Program returns the following parameter:
primary_rc
AP_OK
If the verb does not execute because of a parameter error, the Program returns the following parameters:
primary_rc
AP_PARAMETER_CHECK
secondary_rc
AP_INVALID_RES_NAME

AP_INVALID_LIST_OPTION

If the verb does not execute because one or more of the relevant START_NODE parameters were not set, the Program returns the following parameter:
primary_rc
AP_FUNCTION_NOT_SUPPORTED
If the verb does not execute because the system is not built with network node support, the Program returns the following parameter:
primary_rc
AP_INVALID_VERB
If the verb does not execute because the Node has not been started, the Program returns the following parameter:
primary_rc
AP_NODE_NOT_STARTED
If the verb does not execute because of a system error, the Program returns the following parameter:
primary_rc
AP_UNEXPECTED_SYSTEM_ERROR