Google Groups no longer supports new Usenet posts or subscriptions. Historical content remains viewable.
Dismiss
SAV command and OUTPUT parameter
264 views
Skip to first unread message
Mr. K.V.B.L.
Jun 12, 2013, 1:24:12 PM6/12/13
to
I'm trying to figure out the OUTPUT parameter of the SAV command. I want the command to save a stream-file for the OUTPUT parameter. The stream file has to already exist (nice) or the SAV command fails. According to the online research I've done, 1200 is the CCSID for Unicode. However, in testing SAV and asking it to create this log file, it creates a mostly-unreadable file, leaving me to wonder what it takes to create a readable file.
"touch -C 1200 log_file_name.log" should create a Unicode CCSID file but the SAV command has a lot of 'garbage' mixed in with readable text.
???
Some blurbs from the F1 help for the OUTPUT parameter:
'stream-file-path-name'
Specify the path name of the existing stream file to
which the output of the command is directed.
Note: This parameter is Unicode-enabled. See
"Unicode support in CL" in the CL topic collection in
the Programming category in the IBM i Information
Center at http://www.ibm.com/systems/i/infocenter/ for
additional information.
"touch -C 1200 log_file_name.log" should create a Unicode CCSID file but the SAV command has a lot of 'garbage' mixed in with readable text.
???
Some blurbs from the F1 help for the OUTPUT parameter:
'stream-file-path-name'
Specify the path name of the existing stream file to
which the output of the command is directed.
Note: This parameter is Unicode-enabled. See
"Unicode support in CL" in the CL topic collection in
the Programming category in the IBM i Information
Center at http://www.ibm.com/systems/i/infocenter/ for
additional information.
Mr. K.V.B.L.
Jun 12, 2013, 1:53:36 PM6/12/13
to
CRPence
Jun 12, 2013, 9:00:31 PM6/12/13
to
On 12 Jun 2013 10:53, Mr. K.V.B.L. wrote:
IBM i 7.1 Information Center > Systems management > Backup and recovery
> Backing up your system > Manually saving parts of your system >
Saving user data in your system > Saving file systems
_i Using the Save (SAV) command i_
"...
When you use the SAV command, you can specify OUTPUT(*PRINT) to receive
a report of what the system saved. You can also direct the output to a
stream file or to a user space. The SAV command does not provide the
option to create an output file. The Interpreting output from save (SAV)
and restore (RST) topic describes output file format information from
the SAV and RST commands.
Parent topic: _Saving file systems_
_Related concepts_
_Interpreting output from save (SAV) and restore (RST)_
..."
The above link "Interpreting output..." is included and discussed later,
inline.
>> I want the command to save a stream-file for the OUTPUT parameter.
>> The stream file has to already exist (nice) or the SAV command
>> fails.
http://pic.dhe.ibm.com/infocenter/iseries/v7r1m0/topic/cl/sav.htm
_i Save Object (SAV) i_
"...
Output (OUTPUT)
Specifies whether a list of information about the saved objects is
created. The information can be directed to a spooled file, a stream
file, or a user space.
A stream file or user space is specified as a path name.
For more information on specifying path names, refer to "Object naming
rules" in the CL topic collection in the Programming category in the IBM
i Information Center at http://www.ibm.com/systems/i/infocenter/.
Note: This parameter is Unicode-enabled. See "Unicode support in CL" in
the CL topic collection in the Programming category in the IBM i
Information Center at http://www.ibm.com/systems/i/infocenter/ for
additional information.
*NONE
No output is created.
*PRINT
The output is printed with the job's spooled output.
'stream-file-path-name'
Specify the path name of the existing stream file to which the
output of the command is directed.
'user-space-path-name'
Specify the path name of the existing user space to which the
Unfortunately the reference for finding the "Unicode support in CL"
is not ideal; to have suggested a search on "unicode support in control
language parameter values" would have been more beneficial, such that
the InfoCenter search results are ordered with the most desirable links
presented first. The links are included here, inline:
http://pic.dhe.ibm.com/infocenter/iseries/v7r1m0/topic/rbam6/rbam6unicode.htm
IBM i 7.1 Information Center -> Programming -> Control language -> CL
programming
_i Unicode support in control language i_
"Control language (CL) supports Unicode (UTF-16) parameter values. With
this support, your programs can pass a whole set of Unicode characters
instead of just the job�s EBCDIC set.
...
_Calling Unicode-enabled commands_
Read this information to know how to pass Unicode to a Unicode-enabled
CL command. This information applies to system-provided commands that
have been Unicode enabled as well as any user-written commands that take
advantage of the Unicode-enabled support.
..."
The above "Read this" is a link to the following:
http://pic.dhe.ibm.com/infocenter/iseries/v7r1m0/topic/rbam6/rbam6unicoderelated.htm
IBM i 7.1 Information Center -> Programming -> Control language -> CL
programming -> Unicode support in control language
_i Calling Unicode-enabled commands i_
"...
_CL command support for Unicode_
Several system-provided CL commands support Unicode on some parameters.
These commands include a note in the documentation that states the
parameter is Unicode enabled. Depending on how the command is called,
you can pass these commands a Unicode value for the parameter that can
contain any Unicode character.
...
If a command has been Unicode enabled, this does not affect any other
invocations of the command. For example, there are no changes to any
calls to the command from the QCMD prompt line. However, such calls
cannot take advantage of the Unicode enablement either.
_i How to call the QCAPCMD API to pass Unicode to a CL command i_
When you call the QCAPCMD API, you have the option to pass the entire
string to the QCAPCMD API as an EBCDIC or a Unicode value.
These are the possible CCSID values:
* 0. The command input string is in the job CCSID.
* 1208. The command string is in UTF-8.
* 1200. The command string is in UTF-16.
If you set this value to 1208 or 1200, the entire input string must be
passed in Unicode. That is, all data must be passed as the Unicode
value, not just the parameters you have set to Unicode.
_i How to use UTF-8 source files to pass Unicode to a CL command i_
You can create a source member that can contain any Unicode character
(character that is encoded in UTF-8) and submit this to CL for
processing. ...
...
_i QCMD prompt line support for Unicode i_
The system QCMD prompt line does not support Unicode.
..."
>> According to the online research I've done, 1200 is the CCSID for
>> Unicode.
The term Universal Code with the moniker Unicode is somewhat
deceptive, because there are multiple encodings that might be used for
storing the data:
http://pic.dhe.ibm.com/infocenter/iseries/v7r1m0/topic/nls/rbagsunicodes.htm
IBM i 7.1 Information Center -> Programming -> i5/OS globalization ->
Handling data in globalized applications -> Working with Unicode
_i Different encodings of Unicode i_
"The Unicode standard has several main ways in which a Unicode value can
be encoded. They are UTF-8, UTF-16, and UTF-32. Unicode Transformation
Format (UTF) is the algorithmic mapping from every Unicode value to a
unique byte sequence.
..."
>> However, in testing SAV and asking it to create this log file, it
>> creates a mostly-unreadable file, leaving me to wonder what it
>> takes to create a readable file.
As already noted earlier is already known, and again in the first doc
link in my reply, the "it creates" is contradicted. The SAV does not
*create* a file; i.e. the file must be pre-created [as either a *USRSPC
object or as a STMF]. And of course that effect is also reflected by
the next action from the message quoted in my reply, for which the
"touch" request was performed in QSHell to pre-create the output file as
a text Stream File.
>> "touch -C 1200 log_file_name.log" should create a Unicode CCSID
>> file but the SAV command has a lot of 'garbage' mixed in with
>> readable text.
>>
>> ???
>>
>> Some blurbs from the F1 help for the OUTPUT parameter:
>>
>> 'stream-file-path-name'
>> Specify the path name of the existing stream file to
>> which the output of the command is directed.
>>
>> Note: This parameter is Unicode-enabled. See
>> "Unicode support in CL" in the CL topic collection in
>> the Programming category in the IBM i Information
>> Center at http://www.ibm.com/systems/i/infocenter/ for
>> additional information.
The "Note:" suggesting the *parameter* is "Unicode-enabled" refers to
the available CL command support for the _parameter value_ that can be
specified on that parameter. What the data is, that will be output to
the named file, is not implied [in any way] by that "Note:". Thus the
application of that "Note:", upon deciding to create a STMF with
CCSID(1200), is an effective misinterpretation of what the documentation
intends to suggest.
The OUTPUT() data directed to a STMF is a combination of binary data
and text data. Included as part of that binary data is a CCSID value.
That Coded Character Set Identifier is to be associated with each of the
text\CHAR fields that are defined for the output; that CCSID is defined
in the "Command information entries". As such, a more appropriate use
of the Touch shell command would be the invocation "touch -C 65535
log_file_name.log" to create a _binary stream file_ into which the
OUTPUT() of the SAV command would write its data. The
layout\format\definitions of the /fields/ in the output are defined here:
http://pic.dhe.ibm.com/infocenter/iseries/v7r1m0/topic/rzaiu/rzaiurzaiu004.htm
IBM i 7.1 Information Center -> Systems management -> Backup and
recovery -> Backing up your system -> Backup programming techniques
_i Interpreting output from save (SAV) and restore (RST) i_
"When you use the Save (SAV) command or the Restore (RST) command, you
can direct output to a stream file or to a user space.
If data already exists in the stream file or user space that you
specify, the command writes over that data. It does not append the new
data to any existing data.
...
* Entry header information
http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/rzaiu/rzaiurzaiu401.htm
When a Save (SAV) command or the Restore (RST) command is run, the
output can be directed to a stream file or user area.
* Command information entries
http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/rzaiu/rzaiurzaiu402.htm
This table describes the format of the command output for the SAV and
RST commands.
* Directory information entries
http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/rzaiu/rzaiurzaiu403.htm
This table describes the format of the directory entry output for the
SAV and RST commands.
* Object link information entries
http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/rzaiu/rzaiurzaiu404.htm
Object link information entries are output in the format described in
the table below. The Entry type value in the entry header determines if
the entry associated with the header is a object link information entry.
* Trailer information entry
http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/rzaiu/rzaiurzaiu405.htm
The trailer information entry is output in the format described in this
topic. The Entry type value in the entry header determines if the entry
associated with the header is a trailer information entry. The trailer
information entry is the last entry in the output created by save (SAV)
or restore (RST) commands.
* Output sequence
http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/rzaiu/rzaiurzaiu400.htm
This table shows the sequence of entries in the output when you specify
INFTYPE(*ALL) or INFTYPE(*ERR)
* Field descriptions
http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/rzaiu/rzaiurzaiu406.htm
This information describes possible values for the save (SAV) and
restore (RST) output fields.
..."
> Doing some more reading it looks like this is a data file, not a
> easy-to-read output file like I had hoped. And, so far I have found
> no utility that takes this data file and displays it to the screen.
Correct... the file is not simply a /text/ stream file. Although IMO
poorly described and poorly choosing a ".txt" file extension in their
example, perhaps to mimic what they presume someone has already done
prior to finding the KB article, but possibly further confounding the
user\reader of the document... According to the following IBM Software
Technical Document 29901739 with Document Title "SAV
OUTPUT(Stream-File-Path-Name) Command Example and Considerations", when
"specifying a stream-file-path-name for the OUTPUT parameter, the output
is not discernible" when viewed as a text stream; albeit without that
last clause. Eventually however they clarify that "the format of the
file is BINARY (not EBCIDIC or ASCII). To view the file, users must
write an application to read through the output.":
http://www.ibm.com/support/docview.wss?uid=nas19bec6d0f4811371b86256b44005608d9
Thus the data that is output to the pre-created file is binary data
that a program would need to read, from which a report or database
file(s) could be populated. I have seen the question asked a few times
in different places since 2007, but never any response from anyone that
they have\offer a program to parse nor do anything else with the STMF
output. Note: the choice of a *USRSPC limits data to under 16MB, so its
usage is probably not a very good fit for an OUTPUT() specification on a
SAV request, except when the SAV request is known in advance to be small
enough.
Does the OUTPUT(*PRINT) for the SAV request provide an acceptable
report? If so, then what about using the OVRPRTF command request to
redirect the spooled output to a stream file... given a STMF is the
desirable place to store that information, instead of a spool file.?
_i Override with Printer File (OVRPRTF) i_
"...
To stream file (TOSTMF)
Specifies the directory or stream file where the output data is to be
written. All directories in the path name must exist. New directories
are not created. This parameter is only valid when the Workstation
customizing object (WSCST) parameter is not *NONE, or the Printer device
type (DEVTYPE) parameter is *AFPDS.
If the TOSTMF value refers to a directory, the system will create a
stream file in that directory with a unique name derived from the
printer file name. If the TOSTMF value is a file name, a stream file by
that name must not already exist.
*NONE
The output is written to a spooled file if the SPOOL parameter is
*YES, or directly to the printer device (DEV) if the SPOOL parameter is
*NO.
path-name
Specify the path name for the directory or stream file where you
want the output data to be written.
..."
--
Regards, Chuck
> On 12 Jun 2013 10:24, Mr. K.V.B.L. wrote:
>> I'm trying to figure out the OUTPUT parameter of the SAV command.
http://pic.dhe.ibm.com/infocenter/iseries/v7r1m0/topic/rzaiu/rzaiurzaiu150.htm
>> I'm trying to figure out the OUTPUT parameter of the SAV command.
IBM i 7.1 Information Center > Systems management > Backup and recovery
> Backing up your system > Manually saving parts of your system >
Saving user data in your system > Saving file systems
_i Using the Save (SAV) command i_
"...
When you use the SAV command, you can specify OUTPUT(*PRINT) to receive
a report of what the system saved. You can also direct the output to a
stream file or to a user space. The SAV command does not provide the
option to create an output file. The Interpreting output from save (SAV)
and restore (RST) topic describes output file format information from
the SAV and RST commands.
Parent topic: _Saving file systems_
_Related concepts_
_Interpreting output from save (SAV) and restore (RST)_
..."
The above link "Interpreting output..." is included and discussed later,
inline.
>> I want the command to save a stream-file for the OUTPUT parameter.
>> The stream file has to already exist (nice) or the SAV command
>> fails.
_i Save Object (SAV) i_
"...
Output (OUTPUT)
Specifies whether a list of information about the saved objects is
created. The information can be directed to a spooled file, a stream
file, or a user space.
A stream file or user space is specified as a path name.
For more information on specifying path names, refer to "Object naming
rules" in the CL topic collection in the Programming category in the IBM
i Information Center at http://www.ibm.com/systems/i/infocenter/.
Note: This parameter is Unicode-enabled. See "Unicode support in CL" in
the CL topic collection in the Programming category in the IBM i
Information Center at http://www.ibm.com/systems/i/infocenter/ for
additional information.
No output is created.
The output is printed with the job's spooled output.
'stream-file-path-name'
Specify the path name of the existing stream file to which the
output of the command is directed.
Specify the path name of the existing user space to which the
output of the command is directed.
..."
Unfortunately the reference for finding the "Unicode support in CL"
is not ideal; to have suggested a search on "unicode support in control
language parameter values" would have been more beneficial, such that
the InfoCenter search results are ordered with the most desirable links
presented first. The links are included here, inline:
http://pic.dhe.ibm.com/infocenter/iseries/v7r1m0/topic/rbam6/rbam6unicode.htm
IBM i 7.1 Information Center -> Programming -> Control language -> CL
programming
_i Unicode support in control language i_
"Control language (CL) supports Unicode (UTF-16) parameter values. With
this support, your programs can pass a whole set of Unicode characters
instead of just the job�s EBCDIC set.
...
_Calling Unicode-enabled commands_
Read this information to know how to pass Unicode to a Unicode-enabled
CL command. This information applies to system-provided commands that
have been Unicode enabled as well as any user-written commands that take
advantage of the Unicode-enabled support.
..."
The above "Read this" is a link to the following:
http://pic.dhe.ibm.com/infocenter/iseries/v7r1m0/topic/rbam6/rbam6unicoderelated.htm
IBM i 7.1 Information Center -> Programming -> Control language -> CL
programming -> Unicode support in control language
_i Calling Unicode-enabled commands i_
"...
_CL command support for Unicode_
Several system-provided CL commands support Unicode on some parameters.
These commands include a note in the documentation that states the
parameter is Unicode enabled. Depending on how the command is called,
you can pass these commands a Unicode value for the parameter that can
contain any Unicode character.
...
If a command has been Unicode enabled, this does not affect any other
invocations of the command. For example, there are no changes to any
calls to the command from the QCMD prompt line. However, such calls
cannot take advantage of the Unicode enablement either.
_i How to call the QCAPCMD API to pass Unicode to a CL command i_
When you call the QCAPCMD API, you have the option to pass the entire
string to the QCAPCMD API as an EBCDIC or a Unicode value.
These are the possible CCSID values:
* 0. The command input string is in the job CCSID.
* 1208. The command string is in UTF-8.
* 1200. The command string is in UTF-16.
If you set this value to 1208 or 1200, the entire input string must be
passed in Unicode. That is, all data must be passed as the Unicode
value, not just the parameters you have set to Unicode.
_i How to use UTF-8 source files to pass Unicode to a CL command i_
You can create a source member that can contain any Unicode character
(character that is encoded in UTF-8) and submit this to CL for
processing. ...
...
_i QCMD prompt line support for Unicode i_
The system QCMD prompt line does not support Unicode.
..."
>> According to the online research I've done, 1200 is the CCSID for
>> Unicode.
deceptive, because there are multiple encodings that might be used for
storing the data:
http://pic.dhe.ibm.com/infocenter/iseries/v7r1m0/topic/nls/rbagsunicodes.htm
IBM i 7.1 Information Center -> Programming -> i5/OS globalization ->
Handling data in globalized applications -> Working with Unicode
_i Different encodings of Unicode i_
"The Unicode standard has several main ways in which a Unicode value can
be encoded. They are UTF-8, UTF-16, and UTF-32. Unicode Transformation
Format (UTF) is the algorithmic mapping from every Unicode value to a
unique byte sequence.
..."
>> However, in testing SAV and asking it to create this log file, it
>> creates a mostly-unreadable file, leaving me to wonder what it
>> takes to create a readable file.
link in my reply, the "it creates" is contradicted. The SAV does not
*create* a file; i.e. the file must be pre-created [as either a *USRSPC
object or as a STMF]. And of course that effect is also reflected by
the next action from the message quoted in my reply, for which the
"touch" request was performed in QSHell to pre-create the output file as
a text Stream File.
>> "touch -C 1200 log_file_name.log" should create a Unicode CCSID
>> file but the SAV command has a lot of 'garbage' mixed in with
>> readable text.
>>
>> ???
>>
>> Some blurbs from the F1 help for the OUTPUT parameter:
>>
>> 'stream-file-path-name'
>> Specify the path name of the existing stream file to
>> which the output of the command is directed.
>>
>> Note: This parameter is Unicode-enabled. See
>> "Unicode support in CL" in the CL topic collection in
>> the Programming category in the IBM i Information
>> Center at http://www.ibm.com/systems/i/infocenter/ for
>> additional information.
the available CL command support for the _parameter value_ that can be
specified on that parameter. What the data is, that will be output to
the named file, is not implied [in any way] by that "Note:". Thus the
application of that "Note:", upon deciding to create a STMF with
CCSID(1200), is an effective misinterpretation of what the documentation
intends to suggest.
The OUTPUT() data directed to a STMF is a combination of binary data
and text data. Included as part of that binary data is a CCSID value.
That Coded Character Set Identifier is to be associated with each of the
text\CHAR fields that are defined for the output; that CCSID is defined
in the "Command information entries". As such, a more appropriate use
of the Touch shell command would be the invocation "touch -C 65535
log_file_name.log" to create a _binary stream file_ into which the
OUTPUT() of the SAV command would write its data. The
layout\format\definitions of the /fields/ in the output are defined here:
http://pic.dhe.ibm.com/infocenter/iseries/v7r1m0/topic/rzaiu/rzaiurzaiu004.htm
IBM i 7.1 Information Center -> Systems management -> Backup and
recovery -> Backing up your system -> Backup programming techniques
_i Interpreting output from save (SAV) and restore (RST) i_
"When you use the Save (SAV) command or the Restore (RST) command, you
can direct output to a stream file or to a user space.
If data already exists in the stream file or user space that you
specify, the command writes over that data. It does not append the new
data to any existing data.
...
* Entry header information
http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/rzaiu/rzaiurzaiu401.htm
When a Save (SAV) command or the Restore (RST) command is run, the
output can be directed to a stream file or user area.
* Command information entries
http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/rzaiu/rzaiurzaiu402.htm
This table describes the format of the command output for the SAV and
RST commands.
* Directory information entries
http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/rzaiu/rzaiurzaiu403.htm
This table describes the format of the directory entry output for the
SAV and RST commands.
* Object link information entries
http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/rzaiu/rzaiurzaiu404.htm
Object link information entries are output in the format described in
the table below. The Entry type value in the entry header determines if
the entry associated with the header is a object link information entry.
* Trailer information entry
http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/rzaiu/rzaiurzaiu405.htm
The trailer information entry is output in the format described in this
topic. The Entry type value in the entry header determines if the entry
associated with the header is a trailer information entry. The trailer
information entry is the last entry in the output created by save (SAV)
or restore (RST) commands.
* Output sequence
http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/rzaiu/rzaiurzaiu400.htm
This table shows the sequence of entries in the output when you specify
INFTYPE(*ALL) or INFTYPE(*ERR)
* Field descriptions
http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/rzaiu/rzaiurzaiu406.htm
This information describes possible values for the save (SAV) and
restore (RST) output fields.
..."
> Doing some more reading it looks like this is a data file, not a
> easy-to-read output file like I had hoped. And, so far I have found
> no utility that takes this data file and displays it to the screen.
poorly described and poorly choosing a ".txt" file extension in their
example, perhaps to mimic what they presume someone has already done
prior to finding the KB article, but possibly further confounding the
user\reader of the document... According to the following IBM Software
Technical Document 29901739 with Document Title "SAV
OUTPUT(Stream-File-Path-Name) Command Example and Considerations", when
"specifying a stream-file-path-name for the OUTPUT parameter, the output
is not discernible" when viewed as a text stream; albeit without that
last clause. Eventually however they clarify that "the format of the
file is BINARY (not EBCIDIC or ASCII). To view the file, users must
write an application to read through the output.":
http://www.ibm.com/support/docview.wss?uid=nas19bec6d0f4811371b86256b44005608d9
Thus the data that is output to the pre-created file is binary data
that a program would need to read, from which a report or database
file(s) could be populated. I have seen the question asked a few times
in different places since 2007, but never any response from anyone that
they have\offer a program to parse nor do anything else with the STMF
output. Note: the choice of a *USRSPC limits data to under 16MB, so its
usage is probably not a very good fit for an OUTPUT() specification on a
SAV request, except when the SAV request is known in advance to be small
enough.
Does the OUTPUT(*PRINT) for the SAV request provide an acceptable
report? If so, then what about using the OVRPRTF command request to
redirect the spooled output to a stream file... given a STMF is the
desirable place to store that information, instead of a spool file.?
_i Override with Printer File (OVRPRTF) i_
"...
To stream file (TOSTMF)
Specifies the directory or stream file where the output data is to be
written. All directories in the path name must exist. New directories
are not created. This parameter is only valid when the Workstation
customizing object (WSCST) parameter is not *NONE, or the Printer device
type (DEVTYPE) parameter is *AFPDS.
If the TOSTMF value refers to a directory, the system will create a
stream file in that directory with a unique name derived from the
printer file name. If the TOSTMF value is a file name, a stream file by
that name must not already exist.
*NONE
The output is written to a spooled file if the SPOOL parameter is
*YES, or directly to the printer device (DEV) if the SPOOL parameter is
*NO.
path-name
Specify the path name for the directory or stream file where you
want the output data to be written.
..."
--
Regards, Chuck
0 new messages