Writer instructions

Purpose

Use this page to display a banner announcement on each page of the space. Create the Space announcements page in the master space, outside of the Home branch.

You can version the Space announcements page to enable different banners to be published into different target spaces, however, the banner that is displayed in the versioned (master) space itself only displays the most recently-published banner.  If you find errors in the banner area of your versioned space and you are sure the Space announcements page is set up correctly, try publishing the page to the same space.

For more information, see Space-announcements-banners.

Removing

When an announcement is no longer needed, remove the BMC Space Banner macro.

Translation

Localized spaces using the L10n Viewport theme must change the name of this page to Space announcements l10n.  See Configuring-the-Scroll-ViewPort-theme-for-translated-spaces.

Usage

Choose one or none of the following BMC Space Banner macros.

If your space requires another kind of announcement, you can use this page in coordination with your team lead and editors.

When should I use a space announcement banner?

Use the space organization announcement after you change the content from a book-like organization (such as User Manual, Configuration Manual, and Administration Guide) to the product model.

Use the latest version announcement to push traffic to later versions. You do not need to add this to every previous version, but if you have a specific reason that you want users to be aware—for example, Google searches show content for an obsolete version—use the banner to help users find a relevant version.

When an announcement is no longer needed, remove the BMC Space Banner macro.

Space announcement This documentation space provides the same content as before, but the organization of the content has changed. The content is now organized based on logical branches instead of legacy book titles. We hope that the new structure will help you quickly find the content that you need.

Disguise Existing Extract File

The Disguise Existing Extract File screen is displayed when you select Option 2, Disguise, from the Data-Disguise-Menu.

Use this screen to specify information required for the disguise operation, then enter GO to submit the batch job for disguise.

Hints

  • Before you submit the disguise job, make sure that the Disguise Control File or the Dynamic Privacy Rules Project includes the desired disguise criteria for the objects included in the extract file.
  • It is also recommended that the relationship information in both the extract and disguise control file matches.
  • Also, when using disguise rules with complex criteria, the object that you used to define the criteria originally must be included (not excluded) in the extract file or the disguise may not be successful.
  • For related disguise rules, always define the criteria on the object that contains all of the different unique values (including orphans) to be extracted.

Disguise Existing Extract File

image2021-3-12_17-46-37.png

Enter the requested file information before viewing the JCL or submitting the disguise job with the GO command directly:

DSN Qualifier

The qualifier that replaces the asterisk (*) in the dataset names below.

Extract File

Specify the name of the Extract File that is to be disguised. This file can have been created either with Option 3.7.1 (see File-AID-Extract-for-Db2) or the legacy Option 3.7.3 (Option 3 - Extract from a Table to a Data set).

Any existing Extract File can be disguised; however, a file cannot be disguised more than once.

Important

Disguising an existing delimited Extract File is not supported.

When you had requested an extract with disguise and the disguise step of that extract failed, or you had also set the option to save the pre-disguise records to an encrypted file, you can enter the name of the pre-disguise Extract File here as the Extract File to be disguised. You find the name of the pre-disguise file in the output of the extract job.

The name assigned to the pre-disguise extract file will use the standard File-AID for Db2 routine to generate a "temporary" name. The name will be the user prefix, the mid-level qualifier from the Profile, the word "EXTRACT" and finally the current date and time fields (i.e. D050128.T055709).

Important

If an Extract File created with Option 3.7.1 is on tape or cartridge, specify the name of the Extract Summary File instead of the name of the Extract File on tape. The Extract Summary File was created when the generated extract was saved to tape (see Extract Output Information Area:). If your extract file on tape was created with an earlier release of File-AID for Db2 than 6.2, create a summary file as described in Load - Extract File Specification .

Member

If the file you specified in Extract File is partitioned, you can enter a member name. If you leave this field blank or specify a pattern, File-AID for Db2 displays a Member List pop-up containing a list of members that match the specified pattern. The only valid pattern character is an asterisk (*).

Control Card Dataset

The name of the control card dataset which contains the Load control card information describing the Extract File. This data set is always created when an extract is performed using the legacy extract option (Option 3 - Extract from a Table to a Data set). It contains table information such as column names, lengths and types. The dataset name may be fully-qualified or non-qualified.

Important

If this data set is provided then File-AID for Db2 assumes the Extract File above is in Legacy format. The New Extract format does NOT require this data set.
Blank this field out when the specified Extract File has been created with Option 3.7.1 (see File-AID-Extract-for-Db2)

Disguised Extract File

Specify the name where the disguised extracted data is to be written. Make sure the size allocation is at least the same as the size of the extract file to be disguised. See also Size Allocation of Disguise Extract File.

Member

If the file you specified in Disguised Extract File is partitioned, you can enter a member name. If you leave this field blank or specify a pattern, File-AID for Db2 displays a Member List pop-up containing a list of members that match the specified pattern. The only valid pattern character is an asterisk (*). You can create new members by entering the name of the new member.

VOLSER

If the file specified in Disguised Extract File is non-cataloged or new, specify the volume serial number of the file. For non-cataloged files, a volume serial number is required. For new files, a volume serial number is optional.

Disposition

Specify the disposition of the disguise "to" file. You can extract to existing files with a disposition of OLD. Existing files must conform to the format outlined for the extract file in Extract Dataset Allocation . Specify a disposition of NEW to create a new file.

If you specify NEW in the Disposition field, you must specify the following allocation parameters in the Extract Dataset Allocation Screen screen.

Disguise Selection

Specify with which Disguise process the disguise rules have been defined. When set to 1 (DCF) or 2 (DPR), all extracted objects which have disguise criteria defined in the Disguise Control file (DCF) or in the Dynamic Privacy Rules Project (DPR) will be disguised.

1

Use DCF. Disguise the extracted data using a disguise control file (DCF). This option requires installation of Compuware’s File-AID/Data Solutions.
Before submitting a disguise request with the DCF data disguise option, you must have defined the disguise criteria using Option 7, Data Disguise (see Create-and-Modify-Disguise-Criteria).

2

Use DPR. Disguise the extracted data using a Dynamic Privacy Rules Project (DPR). This option requires installation of Compuware’s File-AID/Data Solutions and the File-AID Data Privacy component of the Topaz Workbench.
Only extract files created with File-AID for Db2 Release 6.2 or higher and Option 3.7.1 can be disguised using DPR. Before submitting a disguise request with the DPR data privacy option, you must have defined the disguise criteria (Dynamic Privacy Rules) using File-AID Data Privacy.

Important

Before submitting the job, be sure to specify a region size large enough to run Java (REGION=0M is suggested, 300M is the minimum) in your jobcard (see also View JCL).

DCF: Control File

Specify the Disguise Control File Name. The Disguise Control File determines what disguise criteria are applied to objects included in this extract. Required for Disguise Selection option 1.

DPR: Repository Name

Specify the name of the Privacy Rules Repository to be used with Disguise Selection option 2 for this extract.

Specify the full repository name (up to 128 characters). Or enter an asterisk (*) by itself for a list of all repositories. Then select the desired repository from the list (see Privacy Repository List Screen).

DPR: Project Name

Specify the name of the Dynamic Privacy Rules Project to be used with Disguise Selection option 2 for this extract. Dynamic Privacy Rules are created with the File-AID Data Privacy component of the Topaz Workbench. The Dynamic Privacy Rules Project keeps track of how to apply the privacy rules to which extracted data element. This option requires installation of Compuware’s File-AID/Data Solutions and File-AID Data Privacy.

Specify the full project name (up to 128 characters) or a pattern ending with an asterisk (*) for a list of matching projects. Asterisk (*) by itself lists all projects. Then select the desired project from the list (see Privacy Project List).

Important

The specified project must exist in the repository you specified in the DPR: Repository Name field, or the message 'Project not found' is displayed.

Create Audit Trail

Specify whether an Audit Trail is to be created for each object being disguised. The Audit Trail will contain the before and after images of each record that was disguised.

N

No. Audit Trail datasets will not be created.

Y

Yes. File-AID for Db2 creates a separate Audit Trail dataset for each disguised object. The naming convention for each Audit Trail dataset is prefix.DSGA.qualifier.Dyymmdd.Thhmmss prefix.

Audit Trail file prefix

Specify the prefix to be assigned to the Audit Trail dataset names. Prefix plus USERID can be up to 14 positions, the remainder of the dataset name will follow the above mentioned naming convention. If prefix is blank, only the USERID will be used. Any value specified will be appended to the USERID. Precede the prefix value with a single quote (‘) to use the value without the USERID.

Primary Commands

The following primary commands are valid:

GO

Submit the batch job for disguise.

JCL

View the JCL generated for the disguise job prior to submitting the job with the SUBMIT command (see also View JCL).

Privacy Repository List

The Privacy Repository List Screen lists all File-AID Data Privacy Repositories when you specified an asterisk (*) in the DPR: Repository Name field of the Disguise Existing Extract File.

Select the desired repository name and press <Enter>.

The following figure shows the Privacy Repository List Screen.

Privacy Repository List Screen

image2021-3-12_17-49-28.png

REPOSITORY NAME

Displays the name of the available File-AID Data Privacy Repository.

When a repository is unavailable (disabled), its entry is marked with an asterisk (*) in the line command column. If you select an unavailable repository, the following short message is displayed:

DISABLED REPOSITORY

Press PF1 to view the long message:

DR076-CANNOT SELECT DISABLED/UNAVAILABLE REPOSITORY

Privacy Project List

The Privacy Project List Screen lists all File-AID Data Privacy projects that match the pattern you specified in the DPR: Project Name field. Select the desired project name and press <Enter> .

The following figure shows the Privacy Project List Screen.

Privacy Project List Screen

image2021-3-12_17-50-8.png

PROJECT NAME

Displays the name of the Privacy Project. You created the Privacy Project with the File-AID Data Privacy plugin of the Topaz Workbench.

Description

Displays the description of a Privacy Project if one was entered when the Privacy Project was with the File-AID Data Privacy plugin of the Topaz Workbench.

View JCL

The ISPF/PDF Edit screen shown is displayed when you enter the JCL command in the Disguise Existing Extract File screen.

The generated JCL can be edited, submitted with the SUBMIT primary command, and saved by using the CREATE or REPLACE primary commands. Saving your generated JCL allows you to postpone execution or rerun the same job at another time.

Extract File Created With Option 3.7.1

When the Extract File was created with the Option 3.7.1, the generated JCL looks similar to what the following figure displays.

View File-AID for Db2 generated JCL for an extract file created with Option 3.7.1

image2021-3-12_17-50-47.png

Important

  1. When disguising the extract with File-AID Data Privacy defined Dynamic Privacy Rules (DPR), specify a region size large enough to run Java (REGION=0M is suggested, 300M is the minimum) in your jobcard. See also Disguise Selection, option 2, DPR.
  2. The FARULES DD identifies the Privacy Rules Repository name and Dynamic Privacy Rules Project ID.
    The FARULES DD may be allocated to a sequential file or a member of a PDS. The record length must be fixed 80 bytes.

XVJPRINT Execution Log Output

File-AID Data Privacy jobs now write execution information to XVJPRINT DD (instead of SYSPRINT DD). If XVJPRINT DD does not exist in your JCL, File-AID will dynamically allocate XVJPRINT.

If you want the execution log output sent to a file, point XVJPRINT DD at a file (instead of SYSOUT=*). This file must be allocated with RECFM=FBA, LRECL=133.

Optional Data Privacy Report Output Written to a File

If you want the Data Privacy Report information written to a fixed layout sequential file and/or to a CSV (Comma Separated Values) file, manually add the appropriate DD statement to the File-AID Data Privacy job.

Important

This functionality requires File-AID Data Privacy Release 17.2.3 or newer.

DPRSTAT1 DD (Fixed Layout Sequential File)

When you add a DPRSTAT1 DD to a File-AID Data Privacy job and it points at a file defined as RECFM=FB,LRECL=2737, at end of job, the file will have the report information for each column written out as a single record containing all the same report information but in a formatted fixed layout sequential file.

Example:

//DPRSTAT1  DD  DSN=fixed_layout_sequential_file,
//              DISP=OLD

or for a new file:

//DPRSTAT1  DD  DSN=fixed_layout_sequential_file,
//              DCB=(RECFM=FB,LRECL=2737,DSORG=PS),
//              SPACE=(TRK,(1,2),RLSE),                            
//              UNIT=SYSDA,    
//              DISP=(NEW,CATLG,CATLG) 


Record Layout for Output File

To view the output file in formatted mode you can use File-AID/MVS Browse or Edit with the following COBOL record layout describing a record in the output file:

01  DPR-STATISTICS.                                      
    15  DPR-COLUMN-NUMBER                  PIC 9(9) COMP.
    15  DPR-NUMBER-CHANGED                 PIC 9(9) COMP.
    15  DPR-NUMBER-INVALID                 PIC 9(9) COMP.
    15  DPR-COLUMN-NAME                    PIC X(128).   
    15  DPR-RULE-NAME                      PIC X(512).   
    15  DPR-RULE-DESCRIPTION               PIC X(512).   
    15  DPR-LAYOUT                         PIC X(1573). 

DPRSTAT2 DD (CSV)

When you add a DPRSTAT2 DD to a File-AID Data Privacy job and it points at a CSV (Comma Separated Values) file defined as RECFM=VB,LRECL=2751, at end of job, the file will have the report information for each column written out as a single record containing all the same report information but they will be Comma Separated Value (CSV) records.

Example:

//DPRSTAT2  DD  DSN=CSV_file,
//              DISP=OLD

or for a new file:

//DPRSTAT2  DD  DSN=CSV_file,
//              DCB=(RECFM=VB,LRECL=2751,DSORG=PS),
//              SPACE=(TRK,(1,2),RLSE),                            
//              UNIT=SYSDA,    
//              DISP=(NEW,CATLG,CATLG) 

Optional Source Data Identifiers (SDIs) Override During Execution

File-AID for Db2 now allows you to replace, during execution of a DPR project, Source Data Identifiers (SDIs) defined in the File-AID Data Privacy project.

To override SDIs, manually add the following DD statement to the JCL:

   //DPRSDI DD DISP=SHR,DSN=u.data.mysdis

where the existing data set u.data.mysdis contains the definitions of SDIs that will be used for this execution.

If the DPRSDI DD is defined in JCL, all SDIs defined in the project will be ignored and replaced with definitions provided in the override data set.

Important

If the specified override file does not exist, Message UNABLE TO OPEN DPRSDI FILE is issued and processing stops with a RC=8.

Override File Format

Replacement SDIs can be defined either in XML or in JSON format. The tags in XML and names in name/value pairs in JSON correspond to SDI properties that can be defined through the Compuware Workbench User Interface. Refer to the Source Data Identifier Overrides topic in the Compuware Workbench File-AID Data Privacy User Guide for more information.

Override Data Privacy Environment Parameters

If you need to, you can override the Data Privacy Environment parameters listed in Data Privacy Environment Parameter Overrides (established with your site’s File-AID Data Privacy Environment parameters. For more information, see File-AID Data Privacy Environment.

Data Privacy Environment Parameter Overrides

Parameter

DD statement

JAVA_VIRTUAL_MACHINE_PATH
(z/OS UNIX Path Name for Java Virtual Machine (JVM))

FAJPATH

JAVAOPNn
(Java (JVM) Options)

FAJOPTS

FILEAID_SERVICES_USER_EXECUTION_PORT
(File-AID Data Privacy IP address and execution port)

FAIPADDR

FILEAID_RULES_ENGINE_PATH
(z/OS UNIX Path Name for File-AID Rules Engine (FARE), formerly Common Disguise Engine (CDE))

FAEXPATH

To do so, insert any of these FAJPATH, FAJOPTS, FAIPADDR, and FAEXPATH DD statements as needed. For example:

//FAIPADDR DD *
127.372.322.101:4180
/*
//FAJPATH DD *
/usr/lpp/java/J7.1_64.bld111513/
/*

It is also possible to specify more than one debug parameter inline. For example:

//FADEBUG DD *
Level=FINER
Filename=/u/userid/
/*

Override Execution Parameter in a Data Privacy Project

In order to override an execution parameter (public variable or translate table) in a Data Privacy Project, add a DPRPARMS DD statement to your JCL. This DD can point to a file or a PDS member containing the override values (maximum record length is 512 bytes). The override values can also be specified inline. Specify override values in the following way:

   executionParm=overrideValue

The execution parameter must have been defined in the Topaz Workbench user interface for the project.

Example:

Your DPR project ‘project1’ includes:

  • 2 translate tables, ‘Title table’ and ‘Titles for HR dept’ (Manage Translate Tables)
    • The source table for ‘Title table’ is file ‘ABC.TRANS’.
  • 2 public variables, ‘scramvar’ and ‘altscram‘ (Process Variables)
    • The initial value for ‘scramvar’ is string ‘123abc’.
  • 2 execution parameters, ‘Parameter1’ identifies the translate table ‘Title table’ and ‘Param2Variable’ identifies variable ‘scramvar’ (Manage Execution Parameters).

At execution time, however, you want to override the defined execution parameters for translate table ‘Title table’ with the new translate table ‘ABC.NEWTRANS’ and the initial value of variable ‘altscram‘ with the new string ‘789xyz’. The new translate table must have the same characteristics as the original one.

To do so, insert the following DPRPARMS DD statement in the JCL (inline example):

//DPRPARMS DD *
Parameter1=ABC.NEWTRANS
Param2Variable=789xyz
/*

Manage Translate Tables

image2021-3-12_18-12-44.png

Process Variables

image2021-3-12_18-13-14.png

Manage Execution Parameters

image2021-3-12_18-13-42.png

Execution Parameter List of Values

If the execution parameter variable type is either a String List or Numeric List, you can also override the list of values.

Specify a list of values in the following way:

   executionParm=LIST(X)=overrideValueXoverrideValueXoverrideValue

The X variable inside the =LIST( )= parentheses defines the delimiter for the list of values. The delimiter can be any character. Connect each overridevalue with the defined delimiter.

For example, insert the following DPRPARMS DD statement in the JCL (inline example) to override the values of the String List named STATE (* is the defined delimiter):

//DPRPARMS DD *
STATE=LIST(*)=MI*OH*RI*CA*MO*IN
/*

Special Instructions for Oracle Translate Table

If your Data Privacy job uses Data Translation with an Oracle Translate Table and your File-AID Data Privacy Environment parameters do not include the following JAVA options (for more information, see File-AID Data Privacy Environment), insert the following FAJOPTS DD statement after the FARULES DD statement:

//FAJOPTS DD *
-verbose:sizes
-Dfile.encoding=UTF-8
-Dlog.encoding=IBM1047

If the JAVA options in the File-AID Data Privacy Environment parameters include other site specific JAVA options, also add them to the FAJOPTS DD statement before submitting the job.

Adding the above FAJOPTS DD statement will override the JAVA options in the File-AID Data Privacy Environment parameters and make it possible to run an Oracle translation while the log will be generated in EBCDIC.

An indicator that you need to make this JCL change is when the Data Privacy job ended with the following error:

   Method execPrivacyRules failed (RC=8) at line nnn in file EXECDPR.C.

However, this general message is not conclusive. Your error log file should have something like the following:

Throwable occurred: java.sql.SQLException: Internal - Unexpected value
at oracle.jdbc.driver.T4CTTIoauthenticate.processRPA(T4CTTIoauthenticate.java:516)
at oracle.jdbc.driver.T4CTTIfun.receive(T4CTTIfun.java:295)
at oracle.jdbc.driver.T4CTTIfun.doRPC(T4CTTIfun.java:186)
at oracle.jdbc.driver.T4CTTIoauthenticate.doOSESSKEY(T4CTTIoauthenticate.java:390)
at oracle.jdbc.driver.T4CConnection.logon(T4CConnection.java:356)
at oracle.jdbc.driver.PhysicalConnection.<init>(PhysicalConnection.java:531)
at oracle.jdbc.driver.T4CConnection.<init>(T4CConnection.java:221)
at oracle.jdbc.driver.T4CDriverExtension.getConnection(T4CDriverExtension.java:32)
at oracle.jdbc.driver.OracleDriver.connect(OracleDriver.java:503)
at java.sql.DriverManager.getConnection(DriverManager.java:322)
at java.sql.DriverManager.getConnection(DriverManager.java:358)

If you see the above, then you need to insert the FAJOPTS DD statement.

Extract File Created With Option 3.7.3

When the Extract File was created with the legacy Option 3.7.3, the generated JCL looks similar to what View File-AID for DB2 generated JCL for a legacy extract file created with Option 3.7.3 displays.

View File-AID for Db2 generated JCL for a legacy extract file created with Option 3.7.3 

image2021-3-12_18-16-49.png

Use this screen to view or edit the JCL generated by File-AID for Db2 to disguise an existing extract file with predefined disguise criteria as specified in the Disguise Control File. Use the SUBMIT command to submit the extract request for execution. If you want to save this JCL, use the ISPF/PDF CREATE or REPLACE command before you exit the panel.

Redirect File-AID/Data Solutions Report (Data Disguise with DCF only)

When using a Disguise Control File (DCF) to disguise data, you can choose to redirect the disguise report output produced by File-AID/Data Solutions to FADSPRNT DD by simply adding it to the JCL. The FADSPRNT DD can point at a file or at SYSOUT.

Since the use of FADSPRNT splits the File-AID/Data Solutions report output away from the File-AID for Db2 report output, FADSPRNT and SYSPRINT must be looked at together to get a complete picture of the job.

Batch JCL from Previous Releases

Migrating JCL for disguising a legacy extract file created with Option 3.7.3 from File-AID for Db2 Release 6.3 to Release 21.01 requires removing the File-AID/Common Components (VJ) load libraries CXVJAUTH and SXVJAUTH. See sample JCL in View File-AID for DB2 generated JCL for a legacy extract file created with Option 3.7.3.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*