Hierarchical file system API support for DDM

The hierarchical file system (HFS) APIs and the functions that they support are part of the i5/OS™ operating system.

The APIs provide applications with a single, consistent interface to all the hierarchical file systems available on your iSeries™ server. They automatically support the document library services (DLS) file system and can support user-written file systems also.

DDM can be registered under HFS as one of the user-written file systems. DDM, however, only supports the copy stream file (QHFCPYSF) HFS API. To register DDM under HFS, you must run the following command on your iSeries source system, CALL QTSREGFS. If no errors occur, DDM is successfully registered with HFS.

Calling DDM using the HFS QHFCPYSF API causes one of two DDM-architected commands to be generated, the LODSTRF (load stream file) or ULDSTRF (unload stream file) command. Both of these DDM commands are part of the stream file DDM model (STRFIL). If the DDM target server you are working with does not support the STRFIL DDM model, then errors will occur when trying to use this support. DDM uses documents and folders (DLS) on the server to copy stream file data either to (ULDSTRF case) or from (LODSTRF case).

To use the DDM HFS copy stream file support, note the following items:

Both the source and destination file path names must begin with the string '/QDDM/' to indicate to HFS that DDM is the file system that will handle the copy stream file function.
The copy information HFS parameter is ignored by DDM, but you still must pass a valid HFS value.
Either the source or destination file path name parameter must be the name of a DDM file, but not both. The DDM file used must point to a target server that supports the STRFIL DDM file model and the remote file name value must end with the string ' FMS' if the DDM file points to another iSeries server.
The other source or destination file path name parameter that is not a DDM file, must be the name of an existing DLS object (document in a folder) and the name must be followed by the string ' FMS'.
The maximum source or target path name length supported by DDM is 63 characters. The 63 characters do not include the '/QDDM/' or the ' FMS' possible appendages.
In the LODSTRF case (source file path name is a local DLS object and target file path name is a DDM file), the local DLS document is read starting at offset zero through the end of the file. Whether the destination file (pointed to by the DDM file) exists or not is dependent on the target server's stream file support.
In the ULDSTRF case (source file path name is a DDM file and destination file path name is a local DLS object), the local or target DLS document must exist on the iSeries and will have its contents cleared and then written to starting at offset zero.

Here is a copy stream file example that will generate a LODSTRF DDM command to a remote server:

CRTDDMF FILE(DDMLIB/DDMFILE) +
RMTFILE(*NONSTD 'TARGET/SYSTEM/
SYNTAX/PATHNAME FMS') RMTLOCNAME(RMTSYSNM)

In this example, the local DLS object is 'PATH1/PATH2/FOLDER1/DOC1'.

You would call QHFCPYSF with the following parameter list:

1   Source file path name = '/QDDM/PATH1/PATH2/FOLDER1/DOC1 FMS'
2   Source file path name length = 34
3   Copy information = valid HFS value that is ignored by DDM
4   Target file path name = '/QDDM/DDMLIB/DDMFILE'
5   Target file path name length = 20

Just reverse the source and destination file path names and lengths to generate an ULDSTRF DDM command.

The example program in the following example calls DDM HFS API:

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information

Figure 1. Program example

/********************************************************************/
/********************************************************************/
/*  FUNCTION: This program copies a stream file using the QHFCPYSF  */
/*            HFS API.                                              */
/*                                                                  */
/*  LANGUAGE: PL/I                                                  */
/*                                                                  */
/*  APIs USED: QHFCPYSF                                             */
/*                                                                  */
/********************************************************************/
/********************************************************************/
TRANSFER: PROCEDURE(SRCFIL,TRGFIL) OPTIONS(MAIN);
 
/* parameter declarations                                           */
DCL SRCFIL CHARACTER (73);
DCL TRGFIL CHARACTER (73);
 
/* API entry declarations                                           */
/*                                                                  */
/* The last parameter, the error code, is declared as FIXED BIN(31) */
/* for the API. This always has a value of zero, specifying that    */
/* exceptions should be returned.                                   */
DCL QHFCPYSF ENTRY(CHAR(73),FIXED BIN(31),CHAR(6),CHAR(73),
                   FIXED BIN(31),FIXED BIN(31))
                   OPTIONS(ASSEMBLER);
 
/********************************************************************/
/*  Parameters for QHFCPYSF                                         */
/********************************************************************/
DCL srclen FIXED BIN(31);
DCL trglen FIXED BIN(31);
DCL cpyinfo CHAR(6);
DCL error_code FIXED BIN(31);
 
/********************************************************************/
/*  Mainline routine                                                */
/********************************************************************/
 
srclen = INDEX(SRCFIL,'  ') - 1;
trglen = INDEX(TRGFIL,'  ') - 1;
cpyinfo = '1     ';
error_code = 0;
/* Copy the stream file                                             */
Call QHFCPYSF(SRCFIL,srclen,cpyinfo,TRGFIL,trglen,
              error_code);
 
END TRANSFER;

Sample command source that can be used with the preceding program:

CMD
     PARM    KWD(SRCFIL) TYPE(*CHAR) LEN(73) +
               PROMPT('SOURCE FILE NAME')
     PARM    KWD(TRGFIL) TYPE(*CHAR) LEN(73) +
               PROMPT('TARGET FILE NAME')