Problem:
This example illustrates how the CBL_FILENAME_CONVERT call-by-name routine can be used to accomplish various filename conversions and measurements.
Resolution:
BUILD W/RELEASE: Net Express v4.0 and up.
INTRODUCTION
==========
The example program includes the code for 10 different conversions and measurements. This "Readme" file includes concise descriptions for each usage. The example program includes these
descriptions together with the code that implements the example.
SOURCE FILES:
==========
Program Files Description
---------------- -----------------------------------------------------------
CBLFNCNV.cbl Example program that illustrates ten different usages of the CBL_FILENAME_CONVERT call-by-name routine.
Other Files Description
---------------- -----------------------------------------------------------
CBL_FILENAME_CONVERT.doc Word document copied from Net Express Help.
OPERATION:
========
The example program is ready to Animate. Right mouse click on the CBLFNCNV.INT file in the Debug Build Window and then click the Animate button. Step through each conversion reading the notes and examining the data items. You can toggle the display of the data items between ANSII
characters and hexadecimal representation to track the actual terminator character. Monitors have been established for these data items:
FNC-FUNC - The CBL_FILENAME_CONVERT function code
FILENAME-IN - The input filename buffer
FILENAME-OUT - The output filename buffer
FNC-IN-LENGTH - The input filename or buffer length
FNC-OUT-LENGTH - The output buffer length
FNC-RET - The CBL_FILENAME-CONVERT return value
(the converted or measured filename length)
RETURN-CODE - The COBOL RETURN-CODE special register
CBL_FILENAME_CONVERT - The syntax
working-storage.section.
77 fnc-func pic x comp-x.
77 filename-in pic x(50).
77 filename-out pic x(50).
77 fnc-in-length pic x(4) comp-5.
77 fnc-out-length pic x(4) comp-5.
77 fnc-ret pic x(4) comp-5.
procedure.division.
call.'CBL_FILENAME_CONVERT'
using by reference fnc-func
by reference filename-in
by reference filename-out
by value fnc-in-length
by value fnc-out-length
returning fnc-ret
A zero (0) return value indicates an error has occurred. Check that your parameters are specified correctly.
A non-zero return value is a filename length and indicates that a conversion or measurement was successful. The terminating character is not included in the length.
A "spacey" file name is one where the path or the filename has embedded space characters: C:\\Documents Settings\\My Best Document.doc
A space terminated filename is one where the last character is a space, and there are no space characters within the filename.
A variant form of the space terminated filename is one where the filename has embedded space characters, but the entire filename is enclosed with quotes, and the terminating space follows the right most quote.
A null terminated filename is one where the last character is a null.
There are five basic function codes for this routine:
0 - converts a space terminator to a null terminator;
1 - converts a null terminator to a space terminator, if the null
terminated filename is spacey, it is also quoted;
2 - inserts a null terminator given a length;
4 - converts a space terminator to a null terminator and capitalizes
the filename;
Note: Function code 4 can be combined arithmetically with codes 1 and 2, providing two additional codes 5 and 6.
5 - converts a null terminator to a space terminator, capitalizes the
filename, and when the filename is spacey, it is quoted;
6 - inserts a null terminator given a length, and capitalizes the
filename;
Note: Function codes 2 and 6 can be used to convert a space terminated, spacey filename to a null terminated filename by specifying the exact length of the spacey filename in the "fnc-in-length" parameter.
Note: Function code 8 can be arithmetically combined with the lesser codes, but the lesser codes are ignored.
8 - returns the length of: a space terminated filename;
a filename that completely fills a data
item with no embedded spaces;
a filename terminated by a special
character defined in filename-out and
fnc-out-length defines the number of
special characters defined, the first
special character found terminates the
scan;
a quoted, spacey filename, that is space
terminated, including enclosing quotes.
Note: When filename-out is not used, it should be passed as a null pointer.
==========================================================
Function code 0 converts a space terminated file name, to a null terminated filename, and returns the converted filename length, not counting the terminator.
Function code 1 converts a null terminated file name, to a space terminated filename, and returns the converted filename length, not counting the terminator.
Function code 1 converts a null terminated, spacey file name, to a space terminated, spacey filename with quotes, and returns the converted filename length, not counting the terminator.
Function code 2 converts a space terminated, spacey file name, of a specific length, to a null terminated, spacey filename, and returns the converted filename length, not counting the terminator.
Function code 4 converts a space terminated file name, to a null terminated, capitalized filename, and returns the converted filename length, not counting the terminator.
Function code 5 converts a null terminated, spacey file name, to a space terminated, spacey filename that is quoted and capitalized, and returns the converted filename length, not counting the terminator.
Function code 6 converts a space terminated, spacey file name, of a specific length, to a null terminated, spacey, capitalized filename, and returns the converted filename length, not counting the terminator.
Function code 8 returns the length of a space terminatied filename, or the length of a filename that completely fills a data item, and returns the length of the filename, not counting the terminator.
Function code 8 returns the length of a filename terminated by a special terminator character, where multiple terminator characters can be defined within filename-out, while fnc-out-length defines how many special termination characters are defined, the first terminator character found terminates the scan, and returns the length of the filename, not counting the terminator.
Function code 8 returns the length of a quoted, space terminated, spacey filename, and returns the length of the file name, including enclosing quotes, not counting the terminator.
REFERENCES
========
==========================================================
Keywords: Example, sample, demo, demonstration, cbl_filename_convert.zip
demo.ex
demo.ne
demo.se
