6 Configuring Access Manager

After installing Oracle Access Manager, you can:

create a SQL package
use the STRSQL command to interactively access data in an Oracle server

All Oracle Access Manager parameters or system values that require modification can be changed using Access Manager commands or through a menu system. These commands and their menus are described in this chapter. It includes the following sections:

Access Manager Commands
CHGSQLDFLT
CHGSQLNET
CHGSQLDBG
CRTORAPKG
CHG2PCPRM

6.1 Access Manager Commands

Before attempting to enter any of the Access Manager commands, you must add the Access Manager library to your library list. To do this, enter the following ADDLIBLE command on any command line:

Note:

If you run the Oracle Access Manager, then it will automatically perform the ADDLIBLE and leave the required library in the library list. If you have not run the Oracle Access Manager, then Oracle Access Manager Commands (listed as the topics included in this chapter) will not run successfully until the library is added to the library list.

ADDLIBLE library_name

where library_name is the name of your Access Manager installation library. The default position is *FIRST.

Then, enter:

GO CMDORAAM

The command displays the Access Manager commands menu.

Example 6-1 Access Manager Commands Menu

_______________________________________________________________________________________
 CMDORAAM                 Oracle Access Manager Commands             System:  HQAS400

 Select one of the following:

          1. Change Oracle Access Manager Default settings
          2. Change Oracle Access Manager OracleÂ Net settings
          3. Change Oracle Access Manager Debug settings
          4. Create an Oracle Access Manager SQL Package
          5. Change Oracle Access Manager Two-phase commit parameters

 Selection or command

===>



 F3=Exit    F4=Prompt     F9=Retrieve     F12=Cancel
 (C) Copyright Oracle Corporation, 2006
_______________________________________________________________________________________

Each of the options on the Access Manager commands menu can be accessed directly by entering the command name from any command line. The commands are listed in the following table:

Table 6-1 Access Manager Commands

Menu Choice	Command Name	Purpose
1	`CHGSQLDFLT`	Changes the Access Manager default settings.
2	`CHGSQLNET`	Changes the OracleÂ Net trace settings.
3	`CHGSQLDBG`	Changes Access Manager debugging parameters.
4	`CRTORAPKG`	Creates a SQL package using the specified source and Oracle server name.
5	`CHG2PCPRM`	Changes Access Manager two-phase commit parameters.

6.2 CHGSQLDFLT

After selecting option 1 on the Access Manager commands menu (or after issuing the CHGSQLDFLT command), the first panel that is displayed confirms which library is to be changed. This should match the library where you installed Oracle Access Manager for AS/400.

Example 6-2 Access Manager Default Options Panel

_______________________________________________________________________________________
                         Oracle Access Manager Default Options
                                                                      System: HQAS400

 Type choices for default option, press Enter.

 Existing Install library name ....ORAAM400    Name




 ===>



 F3=Exit    F4=Prompt     F9=Retrieve     F12=Cancel
 (C) Copyright Oracle Corporation, 2006
_______________________________________________________________________________________

The next panel displays the default user ID and default password that are needed for the Oracle server to which you are connecting. The defaults supplied on the distribution tape are SCOTT/TIGER. You will probably want to change this default for security reasons.

Example 6-3 Access Manager Default Options Panel

_______________________________________________________________________________________
                         Oracle Access Manager Default Options
                                                                      System: HQAS400

 Type choices for default option, press Enter.

 Existing Install library name ..... ORAAM400            Name
 Access Manager default user id .... SCOTT               Userid
 Access Manager default password ... **********          Password
 Access Manager default blocksize .. 100                 Blocksize
 Access Manager default number
    format ......................... *PKDEC              *FLOAT, *PKDEC
 Access Manager default precision .. 9                   0 - 31
 Access Manager default scale ...... 2                   0 - Default precision
 Access Manager NLS Language ....... AMERICAN_AMERICA.WE8EBCDIC37
 Access Manager Two-Phase Commit ... *NO                 *YES, *NO
 Commitment-Control Resource Disposition  *RELEASE           *KEEP, *RELEASE

 ===>                                                           Bottom

 F1=Help    F4=Prompt     F9=Retrieve     F12=Cancel
 (C) Copyright Oracle Corporation, 2006
_______________________________________________________________________________________

The ten fields on the panel in Example 6-3 are described as follows:

Existing Install library name identifies the library that contains the Access Manager program. The default is the Access Manager installation library.

Access Manager default user id specifies the default user ID. The default user ID and default password are used if the USER parameter is not specified in a CRTSQLxxx command or if the CONNECT TO statement is issued without the USER or USING options. If you are concerned about security, then you can change this field to BLANK. This forces you to always explicitly enter a user ID and password to CONNECT. If you do set the user ID to blank and attempt to CONNECT without specifying a user ID, then you will receive an ORA-1017 error.

Access Manager default password specifies the default password for the default user ID. The default user ID and default password are used if the USER or the PASSWORD parameter is not specified in a CRTSQLxxx command, or if the CONNECT TO statement is issued without the USER or USING options.

Oracle recommends that you use the default password only for testing, and that in your application, you imbed the user ID and password. A password, if given, will be encoded.

Access Manager default blocksize specifies the default block size. The Access Manager uses the block size data area to determine the number of rows to retrieve in a single fetch. The default is 100. A SELECT statement must contain the FOR FETCH ONLY clause in order for block fetching to be performed.

Access Manager default number format specifies the DB2/400 data type to use when Oracle describes an Oracle numeric field as being of type NUMBER with a scale and precision of zero.

*FLOAT specifies floating point notation. *PKDEC specifies packed decimal notation with precision set to the default precision, and with scale set to the default scale (refer to "Access Manager default scale" in this list). Oracle functions, such as AVG, COUNT(*), MAX, and SUM, return NUMBER values with precision and scale set to zero. For example, using the default precision and scale values of 9 and 2, respectively, the following SQL statements return the values stated here:

SELECT AVG(DEPTNO) FROM DEPTNO;
25.00 if *PKDEC is specified
2.50E+001 if *FLOAT is specified
SELECT 1/3 FROM DUAL;
.33 if *PKDEC is specified
3.33E-001 if *FLOAT is specified

*PKDEC is the default.

Access Manager default precision specifies the default precision to be used if *PKDEC is specified for Access Manager default number format. The default is 9.

Access Manager default scale specifies the default scale to be used if *PKDEC is specified for Access Manager default number format. The default is 2.

Access Manager NLS language specifies the National Language Support (NLS) language. NLS enables Oracle applications to interact with users in their native language using their conventions for displaying data. The default NLS language can be changed to any valid value. Refer to Appendix B, "National Language Support" for a list of valid values.

Access Manager Two-Phase Commit specifies whether two-phase commit processing is to be enabled. Two-phase commit processing ensures transactional consistency in a heterogeneous environment. If set to *NO, then data might not be synchronized between the local and remote databases. If set to *NO, then DDL statements, such as CREATE and DROP, may be used. If set to *YES, then DDL statements cannot be used.

If your application does not change data on either the AS/400 or on the Oracle server, then you can leave this option as *NO. Also, if you use the Oracle server only to get data (not to change data), then you can leave this option as *NO.

Commitment-Control Resource Release specifies when the commitment control resource (allocated to perform a job) is released. Oracle Access Manager for AS/400 is required (by IBM Access Requester Driver specifications) to use an AS/400 commitment control resource.

If you intend to use Access Manager within the confines of a user-defined commitment control definition, then you need Access Manager to release its commitment control resource when a transactional unit of work ends at a commitment control boundary. You reach a commitment control boundary when a COMMIT or ROLLBACK operation is performed. When Access Manager starts a new unit of work, it then reacquires the required commitment control resource. For this scenario, set Commitment-Control Resource Release to *RELEASE.

If you are not planning to use commitment control definitions external to Oracle Access Manager for AS/400, then you can specify *KEEP for this parameter.

6.3 CHGSQLNET

After selecting option 2 on the Access Manager commands menu (or after issuing the CHGSQLNET command), the first panel that is displayed confirms which library is to be changed. This should match the library where you installed Oracle Access Manager for AS/400.

Example 6-4 Access Manager Network Parameters Panel

_______________________________________________________________________________________
                      Change Oracle Access Manager Network Parameters
                                                                       System: HQAS400
 Type choices for default option, press Enter.

 Existing Install library name ......... ORAAM400              Name





 ===>

 F3=Exit    F4=Prompt     F9=Retrieve     F12=Cancel
 (C) Copyright Oracle Corporation, 2006
_______________________________________________________________________________________

On the next panel, you can change the settings of the OracleÂ Net trace options. Because running an OracleÂ Net trace can adversely affect AS/400 and Access Manager performance, do not change these settings unless you are asked to do so by Oracle Support Services.

Example 6-5 Access Manager Network Parameters Panel

_______________________________________________________________________________________
                      Change Oracle Access Manager Network Parameters
                                                                       System: HQAS400
 Type choices, press Enter.

 Existing Install library name ......... ORAAM400              Name
 Client trace level .................... *OFF                  *OFF, *USER, *ADMIN 




 ===>

 F1=Help    F4=Prompt     F9=Retrieve     F12=Cancel
 (C) Copyright Oracle Corporation, 2006
_______________________________________________________________________________________

The fields on the panel in Example 6-5 are described as follows:

Existing Install library name identifies the library that contains the Access Manager program. The default is the Access Manager installation library.

Client trace level specifies the tracing level for the AS/400 client. Valid values are *OFF, *USER, *ADMIN, and 16. The number 16 gives full trace information. Additional values can be supplied by Oracle Support Services for debugging purposes.

6.4 CHGSQLDBG

After selecting option 3 on the Access Manager commands menu (or after issuing the CHGSQLDBG command), the first panel that is displayed confirms which library is to be changed. This matches the library where you installed Oracle Access Manager for AS/400.

Example 6-6 Access Manager Debugging Options Panel

_______________________________________________________________________________________
                    Change Oracle Access Manager Debugging Options
                                                                       System: HQAS400
 Type choices for debugging options, press Enter.

 Existing Install library name ......... ORAAM400              Name



                                                                         Bottom
 ===>

 F1=Help    F4=Prompt     F9=Retrieve     F12=Cancel
 (C) Copyright Oracle Corporation, 2006
_______________________________________________________________________________________

On the next panel, you can change the debugging settings. The debugging function helps diagnose Access Manager problems. Do not change these settings unless you are asked to do so by Oracle Support Services.

Example 6-7 Access Manager Debugging Options Panel

_______________________________________________________________________________________
                    Change Oracle Access Manager Debugging Options
                                                                       System: HQAS400
 Type choices for debugging options, press Enter.

 Existing Install library name ............ ORAAM400              Name

 Access Manager debugging control string .. 0                     Debug String

 Access Manager trace file ................ ARDTRACE              File

 Access Manager trace library ............. ORAAM400              Library



                                                                         Bottom
 ===>

 F1=Help    F4=Prompt     F9=Retrieve     F12=Cancel
 (C) Copyright Oracle Corporation, 2006
_______________________________________________________________________________________

The fields on the panel in Example 6-7 are described as follows:

Existing Install library name identifies the Access Manager installation library.

Access Manager debugging control string specifies the level of tracing. A 0 (zero) turns off all tracing and a 1 turns on full tracing. The trace output always goes to a member in the file that is determined by the Access Manager trace file and the Access Manager trace library.

Access Manager trace file specifies the qualified file name for trace output under control of the Access Manager debugging control string. The file needs to be created as a SOURCE PHYSICAL FILE with a maximum record length of 240.

Access Manager trace library specifies the library portion of a qualified file name. This field is used along with the Access Manager trace file field to designate a file into which trace members are written. If specified as blank, then a value of QTEMP is used.

This field is relevant only if the Access Manager debugging control string field contains a nonzero value.

6.5 CRTORAPKG

After selecting option 4 on the Access Manager commands menu (or after issuing the CRTORAPKG command), the Oracle SQL Package panel is displayed. Access Manager provides CRTORAPKG to facilitate the development of distributed applications that are targeted for execution against an Oracle server. Access Manager issues the necessary commands to precompile, compile, and bind your application program. Refer to Chapter 8, "Using Access Manager" for information about sample programs.

Example 6-8 Oracle SQL Package Panel

_______________________________________________________________________________________
                                Create Oracle SQL Package
                                                                       System: HQAS400
 Type choices, press Enter.

 File .................................. QSQLCSRC              name
   Library ............................. ARDQA                 name
 Member ................................ XI1                   name
 Language Type ......................... *C                    *C, *RPG, *COBOL
 Oracle server ......................... ORACLETCP
 Activation Group ...................... *New
 Object Type ........................... *PGM
 Batch/Terminal Complile ............... *BATCH
 Target Release ........................ *CURRENT
 Additional pre-compile options ........ 




 ===>

 F1=Help    F4=Prompt     F9=Retrieve     F12=Cancel
 (C) Copyright Oracle Corporation, 2006
_______________________________________________________________________________________

The required input fields on the panel in Example 6-8 are as follows:

File is the name of a file containing the program source.

Library is the name of the library containing the file.

Member is the source member in the file.

Language type is the language type. Valid values are *C, *COBOL, and *RPG.

Oracle server is the name of the target Oracle server. This must match an entry name in ORA(TNSNAMES) and an entry in the RDB directory.

After filling in the data, the file, library, and member entries are verified to ensure that they exist.

Caution:

During compilation, CRTORAPKG attempts to connect to the specified Oracle server. Ensure that your Oracle server and your network connection are active before running CRTORAPKG. You can use STRSQL to check the validity of your connection.

After the compile is complete, check the job log to determine if the package creation was completed successfully. Check the output spool file for the compile. Multiple spool files will exist for each compile. If package creation failed, then check for the following problems:

syntax errors in the program source
missing RDB directory entry
missing or incorrect Oracle server entry name in ORA(TNSNAMES)
unavailable target Oracle server
nonfunctional OracleÂ Net system

The CRTORAPKG command uses the relevant IBM CRTSQLxxx command to pre-process your file. Failure will occur only if the severity level of an error is greater than 30. Some severity level 30 messages are issued because the preprocessor does not recognize some Oracle SQL constructs or functions. For this reason, you must examine the spooled output to determine the validity of any errors of severity level 30.

The IBM precompiler flags any reference to Oracle server sequence numbers (error SQL5001, severity 30) and any reference to non-IBM functions, such as TO_CHAR and TO_DATE (error SQL0105, severity 30), as errors.

After finding and correcting the error, resubmit the job from the CRTORAPKG panel. Ensure that the input information is correct before pressing Enter.

6.6 CHG2PCPRM

This command allows you to change Access Manager two-phase commit parameters. The following panel is displayed:

Example 6-9 Change RID (Resolve In Doubt) Options Panel

_______________________________________________________________________________________
                            Change RID (Resolve In Doubt) Options
                                                                       System: HQAS400
 Installation Library: ORAAM920

 DataQueue Timeout (in seconds) ........  90
 CleanUp Delay (in seconds) ............  30
 Trace Level ...........................  49
 Dead Check Counter .................... 100

 Type options, press Enter.
  1-Add  2=Change  4=Remove

 Opt     Oracle Server Name     Description

         VMS_SRV1               Connect to VMS1X system
         MVS03                  MVS system 3
         MVS_92                 MVS running Oracle 9.2
         PC_GTW_92              WinNT 4.0 server - 9.2
         H920_130               SUN running Oracle 9.2.0
                                                                           Bottom

 F1=Help  F4=Prompt  F9=Retrieve  F10=Switch to PrivID screen  F12=Cancel

 (C) Copyright Oracle Corporation, 2006
_______________________________________________________________________________________

For more information about this panel, refer to Chapter 7, "Distributed Transaction Coordination".