metaclient

Purpose

metaclient is a utility that scans Multiload, Fastload, and TPump load scripts and output files, extracting load information and populating the Client Load Metamodel (CLM).

This utility runs on Windows or Linux.

Description

The metaclient program supports non-unique client load script names. The script qualifier is used in conjunction with the script name to attempt to uniquely identify each script.

Metaclient will version multiple instances of a client load script's executions if versioning is enabled in the MDS repository.

If two scripts have the same name and identification information, the two scripts will be judged to be multiple executions of the same script and the information for the current script being processed will update (overwrite) the existing script information if versioning is not enabled in the MDS repository.

If versioning is enabled in the MDS repository, the information for the current script being processed will update the existing script information.

If a script ID mismatch occurs [a new script or a script whose ID information changes (that is, the script is moved to a different location on the origin system)], the script information will be processed as a new script. There is currently no facility in the metaclient utility to delete old script information.

No versioning of multiple instances of a client load script's executions are stored (although a VersionID property is included in the CLM for future implementation of versioning).

Requirements

Before loading client load script metadata using metaclient, the associated databases, tables, views, and other database objects must already loaded into the DIM. Otherwise metaclient will fail when it attempts to set relationships between objects in the CLM and the associated DIM objects.

You must have read permission on both the script file and optional output file.

The script file and optional output file must be on the system (Linux or Windows) where the program is being run.

Since all script files and output files to be loaded must reside on the system where the metaclient utility is run, transport (move or copy) all external script files and output files from their original system(s) to the metaclient system prior to executing metaclient.

Restrictions

Client Load scripts can come from z/OS, Linux, or Windows platforms but the metaclient utility will only run on Linux, and Windows platforms.

Client Load scripts from z/VM platforms are not supported.

Only ASCII formatted files are supported.

The extraction/load of metadata from interactive client load sessions or directly from tape is not supported.

On Linux, the metaclient utility will only run as a command-line program.

Operating Considerations

Platform Considerations

Client Load scripts can come from z/OS, Linux or Windows platforms but the metaclient utility will only execute on Linux and Windows platforms.

If a z/OS script/output file is being loaded into the MDS repository, it must be transported from the z/OS system to a Linux/Windows system and the file format must be converted from EBCDIC (Extended Binary Coded Decimal Interchange Code) format to ASCII format.

To transport the z/OS script/output file, use the FTP program and specify ASCII mode so that the script/output file will automatically be converted to ASCII format during the transport. Run the FTP program from either the z/OS or Linux or Windows system but generally it is easier to start the FTP program on the z/OS mainframe and then transport the script/output file to the Linux or Windows system.

From z/OS platforms, the metaclient utility will only support those z/OS scripts that can be converted from EBCDIC to ASCII. For instance, support will not be provided for EBCDIC Katakana or Kanji scripts because conversion to ASCII may not always work.

From the Linux or Windows platforms, the metaclient utility will support all of the languages and file formats that MDS currently supports.

Script Considerations

For all scripts the metaclient utility assumes that:

A script file contains only one script

An output file contains only the output from one script

The output contained in the output file was generated by the associated script file

If multiple INMOD routines are specified for a single data source, only the last INMOD routine specified will be stored in the CLM.

Note: The metaclient utility performs minimal syntactic validation of the scripts and output files because it assumes valid, working scripts whose execution generated the output files.

TPump reports the number of records read for each IMPORT task instead of for an individual table/view. The metaclient utility extracts this value from the TPump output file and assigns the same value to the NbrRecordsRead property of all the table(s) and/or view(s) covered by an IMPORT task and prefixes a MINUS sign.

TPump reports the number of records sent to Teradata and the number of records in the error table for each IMPORT task instead of for an individual table/view. So, values in the NbrRecordsSentToTD and NbrErrorsTbl1 properties for each table and/or view covered by an IMPORT task are assigned in a similar manner.

Table 10: metaclient Script Feature
Script Type	Feature	Level of Support
Fastload	Scripts in multifile job	Treated as single, individual script. Not combined to create one large script
Fastload	Statistics in a multifile job	Generated only for the output file of the final script
MultiLoad	Multiple tasks	Not supported
	Variable substitution with utility variables	Not supported
	DELETE task	Linkage between the script and the DIM table is supported Linkage between source and DIM table or between SourceFields and DIM columns is not supported
TPump	Multiple tasks (such as BEGIN LOAD statements)	Not supported
	Variable substitution with utility variables	Not supported
	DELETE task	Linkage between the script and the DIM table is supported Linkage between source and DIM table or between SourceFields and DIM columns is not supported

Syntax

metaclient MDSUser MDSPassword scriptname [-q scriptqualifier] [-o outputfilename][-s targetsystemname]

[-d targetdatabasename][-L Label]

Table 11 shows the metaclient utility input parameters. The Optional/Required column refers to whether the utility needs the information and not whether the parameter must be provided by the user. The table provides a detailed explanation of how the utility can obtain the information for each parameter.

Table 11: metaclient Input Parameters
Parameter	Description	Optional/Required	Explanation
MDSUser	A valid Meta Data Services repository user name	Required	metaclient can obtain the information from user input through: The command line parameter, A parameter file, or MetaManager or MetaBrowse when the utility is run through those programs
MDSPassword	The MDS User password	Required
scriptname	The script name as it exists on the metaclient system The full path on the system (where the script is located) can be included but is not required.	Required	metaclient can obtain the information from user input through: The command line parameter, A parameter file, or MetaManager or MetaBrowse when the utility is run through those programs
[-q] script qualifier	The script’s unique identification information on the system of origin. Use when moving the script from the system of origin to the metaclient system or when the script name exists on multiple systems. Additional text that uniquely identifies the script can be added and can take any format. Maintain the same format among all scripts (such as by platform) so that a text comparison correctly generates a success or failure. The additional text can include: If the system of origin is on Linux or Windows, the script name and a fully qualified path where the script is located on the system of origin. If the system of origin is on a z/O platform, a data set name, a member name, or both, identifying where the script is located Any other information that can be used to uniquely identify the script.	Optional	metaclient can obtain the information from user input through: The command line parameter, A parameter file, or MetaManager or MetaBrowse when the utility is run through those programs If no script qualifier is provided, the script’s load path (as specified in the scriptname parameter) becomes the default script qualifier.
[-o] output filename	The name of the script’s output file. A parameter used to allow the metaclient utility to extract certain status information from the script's output file. Format: [metaclientsystemname:] [path] outputfilename The script's output filename consists of: [Optional] The metaclient system name where the output file is loaded. [Optional] The full path on the metaclient system where the output file is located. [Required] The output filename on the metaclient system.	Required	metaclient can obtain the information from user input through: The command line parameter, A parameter file, or MetaManager or MetaBrowse when the utility is run through those programs If the output file is available, status information is loaded into the CLM. If the output file is not available or not provided through any of these means no status information is loaded into the CLM and the metadata load fails.
[-s] target systemname	The name of the target system. If you specify the target systemname parameter, metaclient will use the value specified instead of information provided in a script.	Required	metaclient can obtain the information from user input through: The command line parameter, A parameter file, or MetaManager or MetaBrowse when the utility is run through those programs metaclient can also obtain the information from the tpid specified in the LOGON statement in a script. If the target system name is not provided through any of these means, then the target database name is unknown and the metadata load fails.
[-d] target databasename	The name of the target database. An optional parameter the metaclient utility can use to obtain the target database name. If you specify the target databasename parameter, metaclient will use the value specified instead of information provided in a script. The order of precedence is: 1 Input parameter 2 DATABASE statement 3 BEGIN statement 4 User name	Required	metaclient can obtain the information from user input through: The command line parameter, A parameter file, or MetaManager or MetaBrowse when the utility is run through those programs metaclient can also obtain the information from: The DATABASE statement of a script¹ The BEGIN statement of a script² The LOGON statement of a script³ If the target database name is not provided through any of these means, then the target database name is unknown and the metadata load fails.
[-L] Label	The name of the Label to be associated with the script Use this parameter used to allow metaclient to specify labelname for a load script.	Optional	metaclient can obtain the information from user input through: The command line parameter, A parameter file, or MetaManager or MetaBrowse when the utility is run through those programs

When the DATABASE statement in the script explicitly sets a default database.

When the BEGIN statement explicitly qualifies the table name with the database name

The utility assumes the user name is also the name of the default database and does not interrogate the target system to find the user’s default database. If the user’s default database name is different from the user name, use one of the other methods to specify the target database. Otherwise, the correct target table is not found and the metadata load fails.

Running MetaClient from Teradata MDS

To launch MetaClient from MetaManager or MetaBrowse:

1 In the main Teradata MDS window, click Tools > Import > MetaClient to display the MetaClient dialog box.

2 Select the command-line parameters that will be passed to the utility and click Load.

To exit this dialog box without running the utility, click Cancel.

The required entries are:

Client Load Script Name – where you can either enter (or Browse to) the name of the script to load the data

Client Load Script Output File – Enter (or Browse to) the output file generated by the load program (Optional).

Target System – Enter the name of the MDS target system (Optional).

Target Database – Enter the name of database of the load program (Optional).

The only optional entry is the Client Load Script Qualifier – Use this for the optional script qualifier string. This string plus the Load Script Name is used to uniquely identify the load script.

Note: Optional/Required column refers to whether the metaclient utility needs the information and not whether the parameter must be provided by the user. Table 11 on page 102 shows the metaclient utility input parameters and provides detailed information on how the utility can obtain the information for each parameter.

For more information, see:

Purpose

Description

Requirements

Restrictions

Operating Considerations

Syntax

Command Line and Parameter File Operation

The input parameters are the same as those shown in Table 11 on page 102. They can be:

Entered on the command line

If the command line option is used, there must be a space separating the optional parameter ID (-q, -o, -s, -d) and the parameter value when specifying the optional parameters. If a parameter value contains spaces or special characters, the entire parameter value must be enclosed in double quotes (“). Enclosing the parameter value in single quotes (') or no quotes will cause an error.

Contained in a parameter file

If the parameter file option is used:

The name of the parameter file will be the only parameter when invoking metaclient as shown in this example:

metaclient paramfilename

The parameter file can have any valid name and can be fully qualified.

The contents of the parameter file must include the required parameter information and can include any or none of the optional parameter information.

Within the parameter file the parameter ordering must be maintained.

The parameter file must specify only one parameter value per line and the list of parameters must be in the following order:

The MDS user name (required)

The MDS password (required)

The Client Load script name (required)

The Client Load script's script qualifier information (optional)

The Client Load script's output file name (required)

The name of the target system (required)

The name of the target database (required)

Note: Optional/Required column refers to whether the metaclient utility needs the information and not whether the parameter must be provided by the user.

Table 11 on page 102 shows the metaclient utility input parameters and provides detailed information on how the utility can obtain the information for each parameter.

If a parameter value in the parameter file contains spaces or special characters, the parameter value does not need to be enclosed in quotes. The entire parameter value can be enclosed in double quotes (“) without causing an error. Enclosing the parameter value in single quotes (') will cause an error.

If an optional parameter is not being specified in the parameter file, a blank line must be inserted to maintain its position in the parameter list if a subsequent optional parameter is specified. If one or more trailing optional parameters are not being specified, blank lines are not required since the EOF will terminate the parameter list with the last specified parameter and any missing optional parameters will not be processed.

An EOF will terminate the parameter list in the parameter file.

Do not include the optional parameter ID (such as the “-q” for the script qualifier parameter) as part of the parameter value in the parameter file because the parameter’s position in the parameter list will indicate which parameter is being specified.