Giovanni's logo
IFS subprocedures
this means Version 2
index
M
power search
blue line

ChkIfsObi2: check an IFS object
Subprocedure chkIFSObj2 checks whether an IFS object exists and can be accessed. If so, it also returns some information about it.

Note 1. This procedure was named chkIFSObj2 to distinguish it from subprocedure chkIFSObj made available by Giovanni B. Perotti for freeware IFSTOOL.

chkIFSObj2
  • Checks IFS object's existence and optionally returns its type, size, and error information.
    Note that if the IFS object size is greater than 2,147,483,647 byte, the object is returned as not found. In such a case, subprocedure ChkIfsObj4 should be used instead.
  • No authority to the object is required to use this subprocedure.
  • *X authority is required for all subdirectories in the object's path. If this authority is lacking, the object is not accessible.
  • If the object is found and is accessible, ChkIfsObj2 returns *on. Otherwise, it returns *off. See parameters, below, for more details.
  • If you don't care about the object's type or size or error details, all parameters except the first are optional.

Required parameter group:
Returned value:  indicator 
*on = object exists and can be accessed
*off = object does not exist or cannot be accessed
Parameters:  Null terminated string of complete path to the object
11a   
(optional)
object type (if successful)
10i 0 
(optional)
number of bytes (if successful)
10i 0 
(optional)
error number
- if successful, contains 0
- otherwise, contains C's error number
256a   
(optional)
error text
- if successful, contains a zero length string
- otherwise, contains the C message text associated with C's error number

Coding examples:

  •  
    D indicator       s               n
    D ifsObj          s            256a   inz('/home/joe/x.y')
    D objType         s             11a   varying
    D objSize         s             10i 0
    D rc              s             10i 0
    D errText         s            256a   varying
    C                   eval      indicator = ChkIfsObj2(%trim(ifsObj):  
    C                             objType:objSize:
    C                             rc:errText)
  •  
    * if you only want to find out if the object is accessible
    C                   eval      indicator = ChkIfsObj2('/home/joe/x.y')  
    * if you also want the object's type
    C                   eval      indicator = ChkIfsObj2('/home/joe/x.y':
    C                             objType)
    * if you also want the object's size
    C                   eval      indicator = ChkIfsObj2('/home/joe/x.y':
    C                             objType:objSize)
    * if you also want C's errno & description when a failure occurs
    C                   eval      indicator = ChkIfsObj2('/home/joe/x.y':
    C                             objType:objSize:
    C                             rc:errText)

ChkIfsObi3: check an IFS object
Subprocedure chkIFSObj3 checks whether an IFS object exists and can be accessed. If so, it also returns more information about it than subprocedure chkIfsObj2.

chkIFSObj3
  • Checks IFS object's existence and optionally returns its type, size, creation timestamp, codepage, CCSID and error information. Note that if the IFS object size is greater than 2,147,483,647 byte, the object is returned as not found. In such a case, subprocedure ChkIfsObj4 should be used instead.
  • No authority to the object is required to use this subprocedure.
  • *X authority is required for all subdirectories in the object's path. If this authority is lacking, the object is not accessible.
  • If the object is found and is accessible, ChkIfsObj3 returns *on. Otherwise, it returns *off. See parameters, below, for more details.
  • If you don't care about the object's type, size, creation timestamp, codepage, CCSID or error details, all parameters except the first are optional.

Required parameter group:
Returned value:  indicator 
*on = object exists and can be accessed
*off = object does not exist or cannot be accessed
Parameters:  Null terminated string of complete path to the object
11a   
(optional)
object type (if successful)
10i 0 
(optional)
number of bytes (if successful)
z   
(optional)
creation timestamp (if successful)
5u 0 
(optional)
codepage (if successful)
5u 0 
(optional)
CCSID (if successful)
10i 0 
(optional)
error number
- if successful, contains 0
- otherwise, contains C's error number
256a   
(optional)
error text
- if successful, contains a zero length string
- otherwise, contains the C message text associated with C's error number

Coding examples:

  •  
    D indicator       s               n
    D ifsObj          s            256a   inz('/home/joe/x.y')
    D objType         s             11a   varying
    D objSize         s             10i 0
    D objCrtStamp     s               z
    D objCodepage     s              5u 0
    D objCCSID        s              5u 0
    D rc              s             10i 0
    D errText         s            256a   varying
    C                   eval      indicator = ChkIfsObj3(%trim(ifsObj):  
    C                             objType:objSize:
    C                             objCrtStamp:
    C                             objCodePage:objCCSID:
    C                             rc:errText)
  •  
    * if you only want to find out if the object is accessible
    C                   eval      indicator = ChkIfsObj3('/home/joe/x.y')  
    * if you also want the object's type
    C                   eval      indicator = ChkIfsObj3('/home/joe/x.y':
    C                             objType)
    * if you also want the object's size
    C                   eval      indicator = ChkIfsObj3('/home/joe/x.y':
    C                             objType:objSize)
    * if you also want the object's creation stamp
    C                   eval      indicator = ChkIfsObj3('/home/joe/x.y':
    C                             objType:objSize:
    C                             objCrtStamp)
    * if you also want the object's codepage
    C                   eval      indicator = ChkIfsObj3('/home/joe/x.y':
    C                             objType:objSize:
    C                             objCrtStamp:
    C                             objCodepage)
    * if you also want the object's CCSID
    C                   eval      indicator = ChkIfsObj3('/home/joe/x.y':
    C                             objType:objSize:
    C                             objCrtStamp:
    C                             objCodepage:CCSID)
    * if you also want C's errno & description when a failure occurs
    C                   eval      indicator = ChkIfsObj3('/home/joe/x.y':
    C                             objType:objSize:
    C                             objCrtStamp:
    C                             objCodepage:CCSID:
    C                             rc:errText)

ChkIfsObi4: check an IFS object
Subprocedure chkIFSObj3 checks whether an IFS object exists and can be accessed. It provides the same information as subprocedure chkIfsObj3, but has no restrictions as to the IFS object size.

chkIFSObj4
  • Checks IFS object's existence and optionally returns its type, size, creation timestamp, codepage, CCSID and error information. Note that object sizes greater than 2,147,483,647 byte are not a problem, as this procedure reports the object size through a 64-bit binary unsigned variable.
  • No authority to the object is required to use this subprocedure.
  • *X authority is required for all subdirectories in the object's path. If this authority is lacking, the object is not accessible.
  • If the object is found and is accessible, ChkIfsObj4 returns *on. Otherwise, it returns *off. See parameters, below, for more details.
  • If you don't care about the object's type, size, creation timestamp, codepage, CCSID or error details, all parameters except the first are optional.

Required parameter group:
Returned value:  indicator 
*on = object exists and can be accessed
*off = object does not exist or cannot be accessed
Parameters:  Null terminated string of complete path to the object
11a   
(optional)
object type (if successful)
20u 0 
(optional)
number of bytes (if successful)
z   
(optional)
creation timestamp (if successful)
5u 0 
(optional)
codepage (if successful)
5u 0 
(optional)
CCSID (if successful)
10i 0 
(optional)
error number
- if successful, contains 0
- otherwise, contains C's error number
256a   
(optional)
error text
- if successful, contains a zero length string
- otherwise, contains the C message text associated with C's error number

Coding examples:

  •  
    D indicator       s               n
    D ifsObj          s            256a   inz('/home/joe/x.y')
    D objType         s             11a   varying
    D objSize         s             20u 0
    D objCrtStamp     s               z
    D objCodepage     s              5u 0
    D objCCSID        s              5u 0
    D rc              s             10i 0
    D errText         s            256a   varying
    C                   eval      indicator = ChkIfsObj4(%trim(ifsObj):  
    C                             objType:objSize:
    C                             objCrtStamp:
    C                             objCodePage:objCCSID:
    C                             rc:errText)

LoadStmf: load a stream file
Subprocedure loadStreamFile loads a stream file in memory.
This may be useful when the stream file data must be processed. An example could be writing the stream file data to the html output buffer through the wrtNoSection subprocedure.

Warnings:
  1. Stream files exceeding the 16 MB size (16,776,704 byte) cannot be loaded in memory.
  2. The user program is responsible, after calling this subprocedure, for releasing the memory dynamically acquired by the subprocedure (see the example below).

Required parameter group:
Return code:  0 = successful operation
-1 = IFS object not found
-2 = not a stream file
-3 = stream file size is 0
-4 = stream file size exceeds 16 Mb
-5 = cannot allocate memory
-6 = stream file cannot be opened
Input parameters:
  • Stmf: path and name of the stream file
  • DataType:
    • BIN - do not perform any CCSID converstion, take the data as they are
    • TEXT - convert the data to the CCSID of the job
Output parameters:
  • DataLength: length of stream file data
  • DataPointer: pointer to the memory area containing the stream file data


Example:
D stmf            s           1024    varying
D rc              s             10i 0
D dataLength      s             10i 0
D dataPointer     s               *
D data            s           1000    based(dataPointer)
 /free
      stmf='/cgidev/conf/httpd.conf';
      rc=LoadStreamFile(stmf:'TEXT':DataLength:DataPointer);
      if rc=0;
         // ... process the stream file data in memory, pointed by "dataPointer" ...
         dealloc(n) DataPointer;  // release the allocated memory
      endif;
      return;