In this section: |
If you want to centralize localized column titles, descriptions, and prompts, and apply them to multiple Master Files, you can create a set of translation files and use the TRANS_FILE attribute in a Master File to invoke them. You can set up the files totally manually, or you can use the LNGPREP utility to prepare the files for translation.
In this section: |
Reference: |
The LNGPREP utility extracts TITLE, DESCRIPTION, CAPTION, and PROMPT attribute values from application Master Files into specially formatted language translation files for each language you need. Once you have the contents of these language files translated, your users can run these applications in the language they select.
LNGPREP does two things. It extracts attribute values from a Master File into language files, and it inserts or updates the TRANS_FILE attribute in the Master File with a value identifying the application folder where the language files reside and a prefix used for naming the set of language files. If the Master File is part of a cluster, LNGPREP will extract translatable strings from every Master File referenced in the cluster, and will update each with the same TRANS_FILE value.
LNGPREP requires an input file listing the three-character codes of the languages you need.
The name of each language file starts with the prefix specified in the TRANS_FILE value, followed by a three-character language code, and the extension .lng.
For example, assume the language input file contains the French and Spanish language codes:
fre spa
If the Master File specifies:
trans_file = xlate/xl_
The language translation files would be in the xlate application folder, named:
Each Master File must have a single base language in which the DESCRIPTION, TITLE, CAPTION, and PROMPT attributes are specified. This language does not need to be English.
LNGPREP extracts these attribute values into the base language file, whose language code, for historical reasons, is eng. In this case, eng does not mean English. It means whatever language the Master File is written in.
The base language file (prefixeng.lng) should never be hand edited. All other lng files must be hand edited by translators, to translate the string values from the base language to the appropriate language.
Translating Applications into English
Since language code eng is reserved to mean base language, you cannot use it to contain English translations of an application whose base language is not English. In those cases, use any of the other English dialect language codes, such as AME, UKE, CAE, or AUE. For example, if the base language is German, specify AME in the languages file, run LNGPREP, and it will produce prefixeng.lng and prefixame.lng files, both in German. Translate the contents of prefixame.lng into English. Leave prefixeng.lng untouched.
Each language file contains a line for each attribute value from a related set of Master Files. Each attribute value has a unique index number assigned to it. For example, if the Master File contains FIELDNAME=PRODUCT_CATEGORY, TITLE='Product,Category', and that TITLE happens to be the 39th translatable attribute value, LNGPREP will produce lng files all containing the line:
39 = Product,Category
Your French translator will edit prefixfre.lng, leaving the index values unchanged while translating the string values, producing, in this case,
39 = Produit,Catégorie
At run time, when the TITLE for field PRODUCT_CATEGORY needs to be displayed, if FOCUS is configured for LANG=FRE, FOCUS looks up "Product,Category" in prefixeng.lng, finds index value 39, looks up 39 in prefixfre.lng, and displays the TITLE as "Produit,Catégorie."
How to: |
Reference: |
You must first create a configuration file containing the three-character language codes for each translation file you need, one language code on each line. The first invocation of LNGPREP for a given Master File adds the TRANS_FILE attribute in that and all related Master Files, creates the base language file by scanning the Master Files for supported attribute values, and creates a copy of the base language file with the correct name for each additional language. Then, a translator has to translate the values in each additional language file from the base language to the correct language for that file.
On each subsequent run, LNGPREP will check for updates to the list of related Master Files and attribute values and update the files as needed. Translators will then have to translate any attribute values added to the language files.
The recommended best practice is to create an app directory solely for the purpose of containing .lng files, and use this appname and a common prefix value for all LNGPREP commands. In addition, put the languages fn.cfg file in this app folder. This will create one set of .lng files for all apps, minimizing the time and effort spent on translation.
LNGPREP FILE n_part_name LNGAPP appname LNGPREFIX prefix LNGFILE appname/fn
where:
Specifies the n-part (app1/app2...) name of a Master File.
Specifies the location where .lng files will be written and updated.
Specifies the literal characters that will precede the three-character language code in the names of the .lng files.
Specifies the appname and filename of a user-created .cfg file containing the list of three-character language codes, one per line. For example, the following file named langretail.cfg contains language codes for American English, French, and Japanese:
ame fre jpn
Assume the lnglist.cfg file contains the language codes fre (French) and spa (Spanish):
fre spa
Issue the following LNGPREP command:
LNGPREP FILE weather/forecast LNGAPP xlate LNGPREFIX tq_ LNGFILE xlate/lnglist
The following language files will be created:
The Master File weather/forecast.mas will be updated with the following attribute:
TRANS_FILE= xlate/tq_
Translators then have to translate the values in xlate/tq_fre.lng and xlate/tq_spa.lng.
How to: |
Reference: |
This release introduces a profile that you can reference in the Master File and is executed during Master File processing. The Master File profile (MFD_PROFILE) is a FOCEXEC that suspends processing of the Master File for a request, executes, and then returns to processing of the Master File. The profile can be used for many purposes but is especially useful for:
Note: You can also create a DBA rule dynamically in the Master File for a specific user without having to create a DBAFILE with rules for all users.
Add the MFD_PROFILE attribute to the FILE declaration in the Master File:
FILE = filename, SUFFIX = suffix, MFD_PROFILE = app/fexname,$
where:
Is any valid file name.
Is the suffix value that specifies the file type described by the Master File. MFD_PROFILE is supported for any file type.
Is the name of the application containing the FOCEXEC to be executed. Specifying the application name ensures that the correct version of the profile is executed, in case there is another FOCEXEC with the same name higher on the application path.
Is the name of the MFD_PROFILE FOCEXEC.
In a MATCH request or a request using MORE, all of the MFD_PROFILE procedures specified in any of the Master Files involved in the request will be executed prior to the request. The profiles will execute in the reverse of their order in the request (the profile for the Master File mentioned last in the request executes first).
FOC(36373) WARNING: MFD_PROFILE DOES NOT EXIST
If you want the lack of the profile to terminate processing, turn the ERROROUT parameter to ON.
-DEFAULT &&COUNTER=1; -IF &&COUNTER EQ 1 THEN GOTO START; -SET &&COUNTER= 2; -GOTO DONE -START MFD_PROFILE request against same Master as original request END -SET &&COUNTER=2; -DONE
The first time the MFD_PROFILE is invoked, &&COUNTER is set to 1, so the part of the MFD_PROFILE request that references the same Master File is executed, and &&COUNTER is set to 2. Since executing this request references the Master with the MFD_PROFILE, it is invoked again. However, since &&COUNTER will now be 2, the MFD_PROFILE request will branch around the part that once again references the same Master File, preventing the MFD_PROFILE from being invoked in an infinite loop.
The following version of the EMPDATA Master File:
The edited EMPDATA Master File is
FILENAME=EMPDATA, SUFFIX=FOC, MFD_PROFILE=baseapp/DDBAEMP,$ VARIABLE NAME = Emptitle, USAGE=A30, DEFAULT=EMPID,$ SEGMENT=EMPDATA,SEGTYPE=S0, $ FIELDNAME=PIN , ALIAS=ID, USAGE=A9, INDEX=I, TITLE='&&Emptitle',$ FIELDNAME=LASTNAME, ALIAS=LN, FORMAT=A15, $ FIELDNAME=FIRSTNAME, ALIAS=FN, FORMAT=A10, $ FIELDNAME=MIDINITIAL, ALIAS=MI, FORMAT=A1, $ FIELDNAME=DIV, ALIAS=CDIV, FORMAT=A4, $ FIELDNAME=DEPT, ALIAS=CDEPT, FORMAT=A20, $ FIELDNAME=JOBCLASS, ALIAS=CJCLAS, FORMAT=A8, $ FIELDNAME=TITLE, ALIAS=CFUNC, FORMAT=A20, $ FIELDNAME=SALARY, ALIAS=CSAL, FORMAT=D12.2M, $ FIELDNAME=HIREDATE, ALIAS=HDAT, FORMAT=YMD, $ $ DEFINE AREA/A13=DECODE DIV (NE 'NORTH EASTERN' SE 'SOUTH EASTERN' CE 'CENTRAL' WE 'WESTERN' CORP 'CORPORATE' ELSE 'INVALID AREA');$ DEFINE TYPE_EMP/I1 = DECODE JOBCLASS(JOBS ELSE 1);,$ DEFINE EMP_TYPE/A10 = IF TYPE_EMP EQ 1 THEN 'FULL_TIME' ELSE 'PART_TIME'; END DBA=USERD,$ USER=USER1,ACCESS=R,RESTRICT=FIELD,NAME=SALARY,$ USER=USER2,ACCESS=R,RESTRICT=VALUE,NAME=SYSTEM, VALUE=DEPT EQ SALES OR MARKETING,$ USER=HR1,ACCESS=R,RESTRICT=VALUE,NAME=SYSTEM, VALUE=SALARY FROM 20000 TO 35000,$ USER=HR2,ACCESS=R,RESTRICT=VALUE,NAME=EMPDATA,VALUE=SALARY GT 0,$ USER=HR3,ACCESS=R,RESTRICT=VALUE,NAME=SYSTEM,VALUE=JOBCLASS EQ (JOBS),$
The DDBAEMP procedure sets a value for the global variable &&Emptitle and creates the JOBS lookup file:
DYNAM ALLOC DD JOBS DA USER1.JOBS.FTM SHR REU
-RUN -SET &&Emptitle = 'Employee ID'; TABLE FILE JOBLIST PRINT JOBCLASS WHERE JOBDESC CONTAINS '2ND' OR '3RD' ON TABLE HOLD AS JOBS END
The following request against the EMPDATA data source allocates the JOBS file and sets the user password to HR3. The EMP_TYPE field and the DBA VALUE restriction for user HR3 use the JOBS file created by the MFD_PROFILE as a lookup table:
DYNAM ALLOC DD JOBS DA USER1.JOBS.FTM SHR REU
-SET &PASS = 'HR3'; SET PASS = &PASS -RUN TABLE FILE EMPDATA " Password used is &PASS " " " "USER1 -- Can't see Salary, reject request" "USER2 -- Can see Sales and Marketing departments only" "HR1 -- Can see salaries from 20 TO 35 K " "HR2 -- Can see everyone " "HR3 -- Can see Part Time only " " " PRINT PIN SALARY DEPT EMP_TYPE ON TABLE HOLD FORMAT HTMLON TABLE SET PAGE NOPAGE ON TABLE SET STYLE * TYPE=REPORT, GRID=OFF, FONT=ARIAL,$ END
On the output, the column title for the PIN field is the value of the &&Emptitle variable set in the MFD_PROFILE procedure, and the JOBS file created by the profile was used in limiting the report output to Part Time employees, which are the only ones user HR3 is allowed to see:
The following version of the EMPDATA Master File specifies an MFD_PROFILE named DDEMP2 and a DBAFILE named DBAEMP2. The MFD_PROFILE will create the DBAFILE by reading security attributes from a sequential file named security.data.
The Master File is:
FILENAME=EMPDATA, SUFFIX=FOC, MFD_PROFILE=DDEMP2,$ SEGMENT=EMPDATA,SEGTYPE=S0, $ FIELDNAME=PIN , ALIAS=ID, USAGE=A9, INDEX=I, TITLE='Employee Id',$ FIELDNAME=LASTNAME, ALIAS=LN, FORMAT=A15, $ FIELDNAME=FIRSTNAME, ALIAS=FN, FORMAT=A10, $ FIELDNAME=MIDINITIAL, ALIAS=MI, FORMAT=A1, $ FIELDNAME=DIV, ALIAS=CDIV, FORMAT=A4, $ FIELDNAME=DEPT, ALIAS=CDEPT, FORMAT=A20, $ FIELDNAME=JOBCLASS, ALIAS=CJCLAS, FORMAT=A8, $ FIELDNAME=TITLE, ALIAS=CFUNC, FORMAT=A20, $ FIELDNAME=SALARY, ALIAS=CSAL, FORMAT=D12.2M, $ FIELDNAME=HIREDATE, ALIAS=HDAT, FORMAT=YMD, $ $ DEFINE AREA/A13=DECODE DIV (NE 'NORTH EASTERN' SE 'SOUTH EASTERN' CE 'CENTRAL' WE 'WESTERN' CORP 'CORPORATE' ELSE 'INVALID AREA');$ END DBA=USERD,DBAFILE=DBAEMP2,$
The file with the security attributes (security.data) follows. The security attributes are the USER, ACCESS, RESTRICT, NAME, and VALUE attributes:
USER1 R NOPRINT SALARY USER2 R VALUE SYSTEM DEPT EQ SALES OR MARKETING HR1 R VALUE SYSTEM SALARY FROM 20000 TO 35000 HR1 W SEGMENT EMPDATA HR2 R VALUE EMPDATA SALARY GT 0
According to these attributes, a user with the password:
The DDEMP2 profile procedure:
The rest of the DBA section will be created by reading each record from the security.data file and writing a corresponding DBA record to the DBAEMP2 Master File.
The DDEMP2 profile procedure follows:
-* FILEDEF the input security.data file (Windows) FILEDEF SECURITY DISK c:\ibi\apps\baseapp\security.data (LRECL 81
-* DYNAM the output DBAEMP2 Master File and the input file (z/OS) DYNAM OUTFI DA USER1.DBAEMP2.MASTER SHR REU DYNAM SECURITY DA USER1.SECURITY.DATA SHR REU
-RUN -* Write out the first part of the DBAEMP2 Master File -WRITE OUTFI FILE=DBAEMP2,SUFFIX=FIX,$ -WRITE OUTFI SEGNAME=ONE,SEGTYPE=S0 -WRITE OUTFI FIELD=ONE,,A1,A1,$ -WRITE OUTFI END -WRITE OUTFI DBA=USERD,$ -* Write out a FILE declaration for the calling Master File, passed as &1 -WRITE OUTFI FILE=&1,$ -* Initialize the variables to be read from the security.data file -SET &USER=' '; -SET &ACCESS=' '; -SET &RESTRICT=' '; -SET &NAME = ' '; -SET &VALUE = ' ';
-* Establish the loop for each record of the security.data file -SET &DONE = N ; -REPEAT ENDLP WHILE &DONE EQ N ; -* Read a record from security.data -READFILE SECURITY -* Check if the end of the security.data file was reached and, -* if so, branch out of the loop -SET &DONE = IF &IORETURN EQ 1 THEN 'Y' ELSE 'N'; -IF &DONE EQ 'Y' GOTO ENDLP1; -* If there is a RESTRICT attribute, go to the label -CHKSTR. -IF &RESTRICT NE ' ' THEN GOTO CHKRSTR; -* If there is no RESTRICT attribute, -* write the USER and ACCESS attributes, and loop for the next record -WRITE OUTFI USER=&USER , ACCESS=&ACCESS ,$ -GOTO ENDLP
-CHKRSTR -* If there is a RESTRICT attribute, check if it has a VALUE attribute -* and, if so, go to the label -CHKVAL -IF &VALUE NE ' ' THEN GOTO CHKVAL; -* If there is no VALUE attribute, -* write USER, ACCESS, RESTRICT, and NAME, and loop for next record -WRITE OUTFI USER=&USER, ACCESS=&ACCESS, RESTRICT=&RESTRICT, NAME=&NAME,$ -GOTO ENDLP
-CHKVAL -* If there is a VALUE attribute, write out USER, ACCESS, RESTRICT, -* NAME, and VALUE, and loop for next record -WRITE OUTFI USER=&USER, ACCESS=&ACCESS,RESTRICT=&RESTRICT,NAME=&NAME, VALUE = &VALUE ,$ -ENDLP -ENDLP1
When run, this procedure creates the following DBAFILE:
FILE=DBAEMP2,SUFFIX=FIX,$ SEGNAME=ONE,SEGTYPE=S0 FIELD=ONE,,A1,A1,$ END DBA=USERD,$ FILE=EMPDATA,$ USER=USER1,ACCESS=R,RESTRICT=NOPRINT,NAME=SALARY ,$ USER=USER2, ACCESS=R, RESTRICT=VALUE, NAME=SYSTEM, VALUE=DEPT EQ SALES OR MARKETING ,$ USER=HR1, ACCESS=R, RESTRICT=VALUE, NAME=SYSTEM, VALUE = SALARY FROM 20000 TO 35000,$ USER=HR1, ACCESS=W, RESTRICT=SEGMENT, NAME=EMPDATA ,$ USER=HR2, ACCESS=R, RESTRICT=VALUE, NAME=EMPDATA, VALUE = SALARY GT 0 ,$
The following request prints the PIN, SALARY, TITLE, and DEPT fields from EMPDATA:
TABLE FILE EMPDATA PRINT SALARY TITLE DEPT BY PIN WHERE PIN GE '000000010' AND PIN LE '000000200' ON TABLE SET PAGE NOPAGE ON TABLE HOLD FORMAT PDF END
To run the request, you must first set a valid user password. The MFD_PROFILE procedure will be run first and will create the dbaemp2.mas DBAFILE.
Running the request by first issuing the SET PASS=USER1 command produces the following report in which the salaries display as zeros because of the RESTRICT=NOPRINT attribute for the SALARY field:
Running the request by first issuing the SET PASS=USER2 command produces the following report in which only the SALES and MARKETING departments display because of the VALUE restriction for the DEPT field:
Running the request by first issuing the SET PASS=HR1 command produces the following report in which only the salaries between 20000 and 35000 display because of the VALUE restriction for the DEPT field:
The sequential data source named VALTEST.DATA contains a list of user names and their associated value restrictions:
SALLY CURR_SAL LT 20000 JOHN DEPARTMENT EQ PRODUCTION TOM CURR_SAL GE 20000
Before reading this file, you must FILEDEF or allocate it:
FILEDEF VALTEST DISK baseapp/valtest.data
Or, on z/OS:
DYNAM ALLOC DD VALTEST DA USER1.VALTEST.DATA SHR REU
The following Master File named EMPDBA is a view of the EMPLOYEE data source. It has a DBA section that uses the global variable &&UID for the USER attribute and the global variable &&VAL for the value test against the EMPINFO segment. It also identifies a Master File profile named DBAEMP3. This profile will obtain the user ID of the connected user and find the correct VALUE restriction by reading the VALTEST.DATA file. By setting the global variables to the correct values, it will insert the appropriate DBA rule into the Master File.
FILENAME=EMPLOYEE, SUFFIX=FOC, MFD_PROFILE=DBAEMP3,$ VARIABLE NAME=&&UID, USAGE=A8 , $ VARIABLE NAME=&&VAL, USAGE=A25, $ SEGNAME=EMPINFO, SEGTYPE=S1 FIELDNAME=EMP_ID, ALIAS=EID, FORMAT=A9, $ FIELDNAME=LAST_NAME, ALIAS=LN, FORMAT=A15, $ FIELDNAME=FIRST_NAME, ALIAS=FN, FORMAT=A10, $ FIELDNAME=HIRE_DATE, ALIAS=HDT, FORMAT=I6YMD, $ FIELDNAME=DEPARTMENT, ALIAS=DPT, FORMAT=A10, $ FIELDNAME=CURR_SAL, ALIAS=CSAL, FORMAT=D12.2M, $ FIELDNAME=CURR_JOBCODE, ALIAS=CJC, FORMAT=A3, $ FIELDNAME=ED_HRS, ALIAS=OJT, FORMAT=F6.2, $ END DBA=DBAUSER1,$ USER=&&UID,ACCESS=R,RESTRICT=VALUE,NAME=EMPINFO,VALUE=&&VAL,$
The following is the MFD_PROFILE procedure:
SET MESSAGE = OFF -SET &VALUETEST = 'NOTFOUND'; -* Find the user ID of the connected user -SET &&UID = GETUSER('A20'); -SET &&UID = TRUNCATE(&&UID); -* Create a HOLD file with the value test for the connected user TABLE FILE VALTEST PRINT VALUETEST WHERE USERNAME EQ '&&UID' ON TABLE HOLD AS USERVAL FORMAT ALPHA END -RUN -READ USERVAL &VALUETEST.A30 -* If the user name was not in the file, type a message and exit -IF &VALUETEST NE 'NOTFOUND' GOTO SETVALUE; -TYPE USER WASN'T THERE -EXIT -SETVALUE -* Set the global variable for the value test to the correct test -SET &&VAL = ''|&VALUETEST||''; -* Set the USER parameter to the user ID of the connected user SET USER = &&UID
The following request displays a report against the EMPDBA view of the EMPLOYEE data source:
USE EMPLOYEE AS EMPDBA END -RUN TABLE FILE EMPDBA PRINT LN FN CURR_SAL BY DEPARTMENT ON TABLE SET PAGE NOPAGE END
Running the request when SALLY is the connected user produces a report of employees whose salaries are less than $20,000:
DEPARTMENT LAST_NAME FIRST_NAME CURR_SAL ---------- --------- ---------- -------- MIS SMITH MARY $13,200.00 JONES DIANE $18,480.00 MCCOY JOHN $18,480.00 GREENSPAN MARY $9,000.00 PRODUCTION STEVENS ALFRED $11,000.00 SMITH RICHARD $9,500.00 MCKNIGHT ROGER $16,100.00
Running the request when TOM is the connected user produces a report of employees whose salaries are greater than or equal to $20,000:
DEPARTMENT LAST_NAME FIRST_NAME CURR_SAL ---------- --------- ---------- -------- MIS BLACKWOOD ROSEMARIE $21,780.00 CROSS BARBARA $27,062.00 PRODUCTION BANNING JOHN $29,700.00 IRVING JOAN $26,862.00 ROMANS ANTHONY $21,120.00
Running the request when JOHN is the connected user produces a report that includes only the PRODUCTION department:
DEPARTMENT LAST_NAME FIRST_NAME CURR_SAL ---------- --------- ---------- -------- PRODUCTION STEVENS ALFRED $11,000.00 SMITH RICHARD $9,500.00 BANNING JOHN $29,700.00 IRVING JOAN $26,862.00 ROMANS ANTHONY $21,120.00 MCKNIGHT ROGER $16,100.00