FILEOPTION

Administration z/OS®		Manager for RACF® z/VM®	Compliance and Auditing z/OS				Adapters for SIEM
Admin	Visual	Manager for RACF® z/VM®	Audit for RACF	Audit for ACF2	Audit for TSS	Alert	Adapters for SIEM
•	•	•	•	•	•	•	•

The FILEOPTION statement sets file options for the specified ddname. If you want to specify global file options, use the OPTION command. See OPTION.

The first FILEOPTION statement for a particular ddname also applies file options specified on previous OPTION statements insofar as these statements are not overridden by the FILEOPTION statement itself. Multiple FILEOPTION statements can be given for the same ddname, but they must precede the first NEWLIST that refers to that ddname. A NEWLIST can refer to a ddname explicitly by the DD= parameter, or implicitly by the DD= parameter of a previous OPTION command.

File options can also be specified on an individual NEWLIST. However, some file options must be the same for all NEWLISTs written to a particular ddname. You cannot override these options, for example, FILEFORMAT=XML and ENCODING=UTF-8. Others can only be partially honored if they differ across NEWLIST types. For example, NOPAGE and PAGELEN=nn influence whether a new data set gets allocated with RECFM=A.

Note that FILEOPTION can also be used for emailed newlists. If the emails are really emailed (not using option SMTPTOFILE) you should use DD=C2REMAIL on the FILEOPTION statement. If SMTPTOFILE is used, you should use DD=C2RSMTP.

As an example, the following commands write a "mount" report to DD MYREPOR1, which uses a page length of 64. The sensitivity report is written to the DD MYREPOR2 which uses a page length of 32.

fileoption dd=myrepor1 pagelength=64
fileoption dd=myrepor2 pagelength=32

option dd=myrepor1

newlist type=mount
 sortlist system mountpoint dsname volser

newlist type=sensitive dd=myrepor2
 sortlist auditpriority sensitivity dsname volser risk auditconcern

Note that for a MERGELIST the FILEOPTION parameters are taken from the first NEWLIST statement within the MERGELIST/ENDMERGE statement. The parameters from the other NEWLISTs are ignored.

The following parameters can be specified as FILEOPTION. The list describes what happens with NEWLISTs that effectively have this parameter (whether it is specified on a FILEOPTION command or directly on the NEWLIST).

CAPS

Output is only in uppercase.

Limitation: DBCS characters in the output for a NEWLIST statement are not affected by the CAPS option if the corresponding NEWLIST statement also has a DBCS option. In all other cases, including a listing of the input commands, DBCS characters are not preserved.

CAPS is incompatible with file formats XML and JSON.

COMPRESS=[GZIP]

For z/OS systems, this parameter can be used to request that the output file is created in gzip format according to RFC 1952. This only works for UNIX files that have been allocated with an ALLOC command with a FILEDESC or PATH specification, see ALLOCATE. The default compression level of 6 is used. This parameter is invalid in combination with CMD, WTO, SNMP, and MAIL. It cannot be used with a DISPLAY command.

DD= ddname ddname=ddname FILE=ddname F=ddname

This defines to which output file the FILEOPTION statement applies. This parameter is required.

ENCODING=EBCDIC ENCODING=UTF-8

For z/OS systems, this parameter indicates that the report will be output in the specified character encoding. By default, the character encoding is EBCDIC. The advantage of UTF-8 output files is that values that are natively in Unicode format (for example, Unicode Db2 fields), can be processed by preserving their value. The default, EBCDIC, means that any values in UTF-8 get converted to the best possible EBCDIC representation possible, exploiting substitute characters where no proper mapping exists. ENCODING=UTF-8 uses the value of the OPTION MY_CCSID setting to derive the correct conversions.

Note that an UTF-8 file can be a Unix file or a data set. UTF-8 data sets cannot be processed well on the mainframe except to copy or FTP to another file format. Specifically, the ASA carriage control column in RECFM=VBA data sets will contain page or line feeds in UTF-8, and RECFM=VB files are not generated with a line feed per record at all.

The option ENCODING=UTF-8 is mutually exclusive with WTO, SNMP, and CMD.

If the proper UNICODE environment has not been set up, the CKR0917 message is issued, and the run terminated. By suppressing this message, fallback to a simple low-128 ASCII translation scheme is possible, but this is not the best option for production purposes.

Example:

To send out a UTF-8 encoded report in an email attachment, you can use the following CARLa statement.

fileoption dd=C2REMAIL encoding=UTF-8
newlist type=racf,
  mailto=rcpt@exampledomain.com,
  from=sender@exampledomain.com,
  outputformat=attach
 select class=user segment=base special
 sortlist key(8) pgmrname

FILEFORMAT=XML FILEFORMAT=TEXT FILEFORMAT=JSON

This keyword can be used to specify the format of an output file. TEXT specifies that no special formatting will be done.

JSON means that the output file must be in the form of a JSON (JavaScript Object Notation) document. The specification of FILEFORMAT=JSON is mutually exclusive with NEWLIST options WTO, CMD, SNMP, and PAGELENGTH, and with the MERGELIST and DISPLAY commands.

XML means that the output file should be in the form of an XML (Extended Markup Language) document. The specification of FILEFORMAT=XML is mutually exclusive with NEWLIST options WTO, CMD, SNMP, and PAGELENGTH, and with the DISPLAY command.

For any field written to be written to an FILEFORMAT=XML file, output modifiers TOPTITLE, TITLE, PAGE, PREFIX, and WRAP are forbidden. Literal strings have no meaning and are forbidden. However, a fixed literal content for an element can be created by a DEFINE element(HB ,"literal") TRUE.

The XML document generated will follow the general structure for XML: a header, a DTD (Document Type Definition) describing the document structure, and a single root element that contains the actual information output by LIST/SORTLIST/SUMMARY. The single root element is the ddname (filename) chosen. The root element has the creation= attribute for the creation time stamp in xsd:dateTime format. The structure of the rest of the document with the actual NEWLIST-specific output depends on whether there is a MERGELIST specification or not.

Without a MERGELIST, one data element per NEWLIST record will be written. The element name for a NEWLIST record is taken from the NEWLIST NAME= parameter. Hence this parameter is required with FILEFORMAT=XML. Within the NEWLIST record element, a sub-element will be present per non-empty field specified on the (SORT)LIST/SUMMARY statement. If the field is missing, then the sub-element will be omitted. When a field has multiple values, the sub-element will be repeated (unless the HORIZONTAL modifier is used). A field name can only occur once per NEWLIST. A field name cannot be the same as a NEWLIST name that is being output to the same XML document (output file). The XML element name can be overridden by specifying a string modifier (column header). The overriding string is used only if the string conforms with XML element name restrictions; otherwise, the uppercase field name is used.

Example:

fileoption dd=myxml fileformat=xml
n dd=myxml type=system name=SYS
 list system mvslvl

Creates XML document body:

<MYXML creation="2005-12-06T14:12:32.66+01:00">
<SYS>
<SYSTEM>DINO</SYSTEM>
<MVSLVL>SP7.0.4</MVSLVL>
</SYS>
</MYXML>

If there is a MERGELIST specification, the records within the mergelist are output as an element with a common name set to the MERGELIST NAME= parameter. The fields that are shared between all mergelist members are output as sub-elements of the NEWLIST type element. The non-shared fields are encapsulated in an element set to the member NEWLIST NAME= parameter (as for the non-MERGELIST, case but as a sub-element of the MERGELIST).

Example:

fileoption dd=myxml fileformat=xml
mergelist name=SOFTWARE dd=myxml
n type=system name=MVS
 list system mvslvl
n type=system name=ESM
 list system esmlvl
endmerge

Creates XML document body:

<MYXML creation="2005-12-07T15:23:04.78+01:00">
<SOFTWARE>
<SYSTEM>DINO</SYSTEM>
<MVS>
<MVSLVL>SP7.0.4</MVSLVL>
</MVS>
</SOFTWARE>
<SOFTWARE>
<SYSTEM>DINO</SYSTEM>
<ESM>
<ESMLVL>HRF7707 OA03853</ESMLVL>
</ESM>
</SOFTWARE>
</MYXML>

FILE_LONGNAME=[name|'name'|"name"|`name`]

This parameter can be used as a longer, maximum 255-character and case-sensitive alternative for file DD name. It is ignored if FILE_UNNAMED_ARRAY is also specified for FILEFORMAT=JSON.

FILE_UNNAMED_ARRAY

This parameter can be used for FILEFORMAT=JSON files to modify the file output from one object with a named array of newlists to an unnamed array of newlists. It causes a FILE_LONGNAME parameter to be ignored. When using this parameter, it is the responsibility of the CARLa writer to ensure that the resulting output complies with the JSON standard; the engine does not enforce that.

FILE_UNNAMED_OBJECT

This parameter can be used with FILEFORMAT=JSON to suppress the file-level object name. It can be combined with NEWLIST SUPPRESS_OBJECT to dynamically generate a name for the object from the first NEWLIST writing to the file. When using this parameter, it is the responsibility of the CARLa writer to ensure that the resulting output complies with the JSON standard; the engine does not enforce that.

LINELEN= value LINELENGTH=value LL=value

This option can be used to set the length of lines that are output by IBM® Security zSecure Admin. If IBM Security zSecure Admin controls the LRECL specification of the output DD when calling from JCL with no LRECL= specification, or when dynamically allocating the data set, this parameter influences the LRECL of the resulting data set. IBM Security zSecure Admin uses the largest line length found for all NEWLISTs directed to a particular file. If IBM Security zSecure Admin writes to an existing data set, or LRECL= is specified for the file, the line length cannot become larger than this value.

To get the page number in the proper position for a narrow print, specify LL=79.

Note: The Print Summary at end of the CARLA SYSPRINT output does not use the LINELEN value. Instead, the LRECL of the file is used to print the Print Summary.

Use of this parameter is not compatible with FILEFORMAT XML and JSON.

MAXP= number MAXPAGE=number PRTMAXP=number

This parameter can be used to limit the amount of output that is actually printed. All data is still read and formatted, but printing will stop the moment the specified number of pages has been reached.

NONULLS

This keyword can be specified to turn off the printing of hexadecimal nulls in the (sort)list report(s). They will be replaced with blanks. See also the NULLS keyword. Note that with XML output, trailing null characters are trimmed off; other null characters are replaced by · (a bullet character).

NOPAGE

This option suppresses all titles and headers which would normally be written above each page for sortlist output, unless specifically requested, such as COLUMN=HEADER. If IBM Security zSecure controls the RECFM specification of the output DD (when calling from JCL with no RECFM= specification, or when dynamically allocating the data set), and all NEWLISTs writing to this DD effectively have NOPAGE, then IBM Security zSecure creates a RECFM=VB data set; otherwise a RECFM=VBA data set.

NOXML_DATADICT

This option turns off generating a data dictionary when XML output is requested (option FILEFORMAT=XML). See also option XML_DATADICT. By default the data dictionary is not generated.

NOXML_DTD

This option turns off generating a DTD (Document Type Definitions) when XML output is requested (option FILEFORMAT=XML). See also option XML_DTD. By default the DTD will be generated unless XML_STYLESHEET=IMBED has been specified.

NULLS

This keyword can be specified to turn on the printing of hexadecimal nulls in the (sort)list report(s). This is the default setting. See also the NONULLS keyword. Note that with XML output, trailing null characters are trimmed off; other null characters are replaced by · (a bullet character).

OVERPRINT= number OVP=number

Number of overprints to get bold text on impact printers. Values must be in the range 0 to 9. Specifying 0 disables overprinting, and is the default. It is only used if the output file has RECFM=A and OPTCD=J is not included in the DCB parameters of the DD.

PAGELEN=number PAGELENGTH=number PL=number

Number of lines on each page to be used for printing. The default is 0 for LIST commands in the domain of a NEWLIST, and 56 for SORTLIST commands, and for the files SYSPRINT and CKREPORT. The minimum is 6, the maximum is 32767.

PL=0 is equivalent to specifying NOPAGE, except that PL=0 prints page headers on the first page in the output file. You should use NOPAGE with (SORT)LIST to suppress page headers, e.g. for command generation.

If IBM Security zSecure controls the RECFM specification of the output DD (when calling from JCL with no RECFM= specification, or when dynamically allocating the data set), and all NEWLISTs writing to this DD effectively have PL=0, then IBM Security zSecure creates a RECFM=VB data set; otherwise a RECFM=VBA data set.

The PL= option is ignored with FILEFORMAT=XML and JSON; NOPAGE is implied instead.

SMTPCLASS= sysoutclass

Specifies the JES output class to be used for the SMTP output processing. When no class is specified, email will be sent to the default class: B.

SMTPNJENODE= nodename

Specifies the JES destination to which email will be routed for final processing. If the SMTP server is running on your local system, this parameter can be omitted.

SMTPWRITER= name

Specifies a name for use in SMTP when selecting an email SYSOUT data set. The external writer name is equal to the SMTP address space name. When no writer is specified, email will be sent to the default writer: SMTP.

TOPTITLE=text, TT=text

SUBTITLE=text, ST=text

TITLE=text, T=text

PAGETEXT=text

Titles to appear on subsequent output pages. TOPTITLE redefines the page header.

TOPTITLE is only used for LIST/SORTLIST/DISPLAY outside ISPF. TITLE redefines the title line printed below the top title line; SUBTITLE defines a line to be printed below the title line. TITLE and SUBTITLE are also used by DISPLAY commands inside ISPF and by REPORT and VERIFY output. The TOPTITLE parameter redefines the page header string only; the page indicator, page number and date are still printed. The PAGETEXT parameter can be used to redefine the page indicator, which is 'page' by default. The syntax requirements for the title are:

title='string'
title="string"
title=`string `
title=:var

The title string can be specified as a string enclosed in single, double or left quotation marks. The string can cross the line boundary, simply continue typing at the start of the next line. In the command listing, the string continuation is indicated by a + following the line number. Alternatively, an ISPF variable name can be passed prefixed by a colon. The content of the ISPF variable is used as the title. The implicit function pool, shared variable, and profile pool will be searched for the variable name.

See also General output modifiers: Controlling field output: title and toptitle.

XML_DATADICT

This option turns on generating a data dictionary when XML output is requested (option FILEFORMAT=XML). The data dictionary contains information about the characteristics of each generated report: the title, top title, and subtitle, and at the field level the field's format, its effective width, its alignment, its (prefix) header, and an indication whether it is a repeated field.

These formatting hints can be exploited by XSLT stylesheets so that many reports can be accommodated by a single stylesheet. Using a data dictionary is required when using the XSLT stylesheet supplied with IBM Security zSecure. See also option XML_STYLESHEET.

This option can be overridden with NOXML_DATADICT. By default the data dictionary is not generated.

XML_DTD

This option turns on generating a DTD (Document Type Definitions) specification when XML output is requested (option FILEFORMAT=XML). This specification can be used by XML processors to validate the document, and to get a better understanding of the structure of the XML document.

This option can be used to override an earlier NOXML_DTD. It cannot be specified when requesting an imbedded stylesheet using XML_STYLESHEET=IMBED. By default the DTD will be generated unless XML_STYLESHEET=IMBED has been specified. See also option NOXML_DTD.

XML_STYLESHEET=NO XML_STYLESHEET=URI("uri") XML_STYLESHEET=IMBED(ddname=ddname,MEMBER=member)

When XML_STYLESHEET=URI("uri") is specified, an

<?xml-stylesheet
type="text/xsl" href="uri"?>

processing instruction is added to the prolog of the XML document. Make sure that the recipient of the report has access to the XSLT stylesheet identified by the URI specified in the processing instruction.

When XML_STYLESHEET=IMBED(ddname=ddname,MEMBER=member) is specified, the XML data is imbedded in the specified XSLT stylesheet, resulting in one output file containing both the XSLT stylesheet and the XML data. A processing instruction is added to transform the XML document by itself, so opening just this one XML file with a web browser (or any other program that supports XSLT stylesheets) shows the transformed result. You can use imbedding to guarantee that the recipient of the report has the XSLT stylesheet available. You can specify ddname=CKRCARLA or omit the ddname= clause to use the default CARLa library (ddname CKRCARLA or as specified on ALLOC DDCARLA). The resulting XML data must be saved with extension xml, or served as mimetype application/xml. The zSecure documentation includes an example of an XSLT stylesheet to transform the XML data to nicely formatted HTML tables in member C2RXSL01 in the SCKRCARL data set. Select your zSecure version and go to the Samples topic. This generic XSLT stylesheet can transform most tabular reports specified in CARLa. Using this XSLT stylesheet allows looking at the data in a web browser, and importing the data into Microsoft Excel.

The stylesheet supplied with IBM Security zSecure can be used for both linking from the XML, and imbedding the XML, for example, with

fileoption dd=output fileformat=xml xml_datadict
   xml_stylesheet=uri("https://ibm.com/docs/en/SS2RWS_3.1.0/
                       com.ibm.zsecure.doc_3.1.0/landing/c2rxsl01.xsl")

fileoption dd=output fileformat=xml xml_datadict xml_stylesheet=imbed(m=c2rxsl01)

Note that, for security reasons, most modern web browsers have restrictions on using XML and XSLT style sheets from local disk or on different internet domains. Depending on the browser, XML output might not get transformed.

To use the stylesheet supplied with IBM Security zSecure, an XML data dictionary must be included with the XML. See XML_DATADICT. The XSLT stylesheet only handles tabular reports. If a MERGELIST report is created, all columns in all SORTLIST/SUMMARY statements in the MERGELIST must be the same. The title used on the generated HTML page is the default top title or explicit TOPTITLE from the first NEWLIST in the report. Every separate report shows the title and subtitle specified on the NEWLIST (or the first NEWLIST in case of a MERGELIST).

You can also create and use your own XSLT stylesheet. The stylesheet must be in EBCDIC format. The <xsl:stylesheet> and </xsl:stylesheet> elements must be on separate lines and be the only elements on those lines.

XML_STYLESHEET=NO turns off generating the processing instruction.

If XML_STYLESHEET=IMBED is specified, no DTD will be generated. In this case, XML_DTD cannot be specified. See option XML_DTD. By default, no xml-stylesheet processing instruction will be generated.

Examples

The following example creates a RACF user report on z/OS UNIX, which links to an XSLT stylesheet. The allocation is done using alloc type=output, but could have also been done using other allocation, JCL for example.

alloc type=racf backup active

alloc type=output dd=auditrpt,
   path='/u/reports/user-special-report-dd060717.xml'
fileoption dd=auditrpt encoding=UTF-8 fileformat=XML xml_datadict,
   xml_stylesheet=uri("https://ibm.com/docs/en/SS2RWS_3.1.0/com.ibm.zsecure.doc_3.1.0/
                       landing/c2rxsl01.xsl")
newlist type=racf dd=auditrpt name=userrpt
   select class=user segment=base special
   sortlist key(8) pgmrname revoke(1,hb) revoke_inactive(1,hb),
      restricted(1,hb) protected(1,hb)

The following example creates an ACF2 logonid report on z/OS UNIX, which links to an XSLT stylesheet. The allocation is done using alloc type=output, but could have also been done using other allocation, JCL for example.

alloc type=acf2 backup active

alloc type=output dd=auditrpt,
path=’/u/reports/user-special-report-dd060717.xml’
fileoption dd=auditrpt encoding=UTF-8 fileformat=XML xml_datadict,
xml_stylesheet=uri("https://ibm.com/docs/en/SS2RWS_3.1.0/
                    com.ibm.zsecure.doc_3.1.0/landing/c2rxsl01.xsl")
newlist type=acf2_lid dd=auditrpt name=userrpt
sortlist logonid name

The following example creates an SMF report on RACF and ACF2 systems running on z/OS. It uses an imbedded stylesheet.

alloc type=smf active
alloc type=ckfreeze dsn=SYSAPPL.DAILY.CKFREEZE

alloc type=output dd=auditrpt,
   path='/u/reports/smf-special-report-dd060717.xml'
fileoption dd=auditrpt encoding=UTF-8 fileformat=XML xml_datadict,
   xml_stylesheet=imbed(m=c2rxsl01)

newlist type=smf dd=auditrpt name=smfrpt
   select userid:special
   sortlist datetime recorddesc

The following example creates a similar SMF report for RACF systems running on z/VM (UTF-8 encoding does not apply). It uses an imbedded stylesheet.

alloc type=smf active
alloc type=racf active
alloc type=ckfreeze cmsfile='DAILY CKFREEZE *'

alloc type=output dd=auditrpt,
   path='/u/reports/smf-special-report-dd060717.xml'
fileoption dd=auditrpt fileformat=XML xml_datadict,
   xml_stylesheet=imbed(m=c2rxsl01)

newlist type=smf dd=auditrpt name=smfrpt
   select userid:special
   sortlist datetime recorddesc