Stata 15 help for mf_st_lchar

Title

[M-5] st_lchar() -- Obtain/set "long" characteristics

Syntax

void st_lchar(basename, charname, string scalar s)

string scalar st_lchar(basename, charname)

void ado_intolchar(basename, charname, macname)

void ado_fromlchar(macname, basename, charname)

where basename, charname, and macname are string scalar.

Description

These functions concern obtaining and setting characteristics that might be longer than 67,784 bytes. To obtain and set characteristics in the usual case, you code

s = st_global("_dta[example]") // obtain

st_global("_dta[example]", s) // set

See [M-5] st_global.

The maximum length of a characteristic is 67,784 bytes whether you are running Stata/IC, Stata/SE, or Stata/MP. Macros can be longer than that. These functions allow saving Stata macros in characteristics and vice versa, and they handle the problem that macros can exceed the maximum allowed length of Stata's characteristics.

st_lchar() is for use by Mata programmers:

1. st_lchar(charname, basename, s) saves s in "long" characteristic basename[charname].

2. st_lchar(charname, basename) returns the contents of "long" characteristic basename[charname].

3. st_lchar(charname, basename, "") can be used to delete "long" characteristic basename[charname].

ado_intolchar() and ado_fromlchar() are for use by Stata ado-file programmers:

1. ado_intolchar(basename, charname, macname) saves the contents of local macro macname in "long" characteristic basename[charname].

2. ado_fromlchar(macname, basename, charname) places the contents of "long" characteristic basename[charname] into local macro macname.

3. Ado-file programmers use the same function as Mata programmers to delete a characteristic: st_lchar(charname, basename, "") deletes "long" characteristic basename[charname].

Remarks

Remarks are presented under the following headings:

Introduction Example 1 -- Ado-file usage Example 2 -- Mata usage

Introduction

Stata macros can be longer than Stata dataset characteristics. The maximum length of a characteristic is 67,784 bytes. Macros are longer than that. How much longer macros can be depends on maxvar because maximum macro length is defined to be sufficient to hold all the names in possible Stata datasets, with a space between, plus some more.

In Stata/IC, the maximum number of variables is 2,048. Variable names can be 32 Unicode characters, which can be as long as 128 bytes. With a space between variable names, macros must allow at least 2,048*129 = 264,192 characters.

In Stata/MP, the maximum number of variables is 5,000 by default and can be set up to 120,000. Thus, the maximum length of macros must allow at least 5,000*129 = 645,000 to 120,000*129 = 15,480,000 characters. Yet, in all of these cases, the maximum length of a characteristic remains fixed at 67,784 characters, meaning that saving all the variable names in one characteristic is not generally possible.

In Stata/SE, the maximum number of variables is 5,000 by default and can be set up to 32,767. Thus, the maximum length of macros must allow at least 5,000*129 = 645,000 to 32,767*129 = 4,226,943 characters. Yet, in all of these cases, the maximum length of a characteristic remains fixed at 67,784 characters, meaning that saving all the variable names in one characteristic is not generally possible.

Programmers will sometimes want to save a varlist in a characteristic and the varlist might be long. Stata saves characteristics in the Stata .dta dataset and programmers save information in characteristics when they are a property of the dataset rather than of the current session or the current analysis. A program providing data certification, for instance, might need to save the names of the variables so that those names could later be compared with the current names to determine whether any variables had been added or dropped.

These functions provide the solution to the different-length problem. Think of these functions as creating, reading, and writing basename[charname], even though these functions in fact create, read, and write basename[charname1], basename[charname2], ..., using however many separate characteristics are necessary to store what needs to be stored.

For the Mata programmer, st_lchar(charname, basename, s) saves s in basename[charname1], basename[charname2], .... st_lchar(charname, basename) returns what was previously set in basename[charname1], basename[charname2], ....

For the Stata ado-file programmer, the same features are provided, except that values are obtained from and stored in local macros. ado_intolchar(basename, charname, macname) saves the contents of macname into basename[charname1], basename[charname2], .... ado_fromlchar(macname, basename, charname) retrieves the contents of basename[charname1], basename[charname2], ..., and stores the result in macname.

In all of these functions, you do not have to keep track of how many characteristics are actually used. Think of the functions and storing in, fetching from, and deleting basename[charname], even though that is not literally true and, in fact, basename[charname] is never created. The actual characteristics are basename[charname1], basename[charname2], ....

Example 1 -- Ado-file usage

In an ado-file, you want to save the contents of local macro varlist in characteristic _dta[datacert_vl]. Ordinarily you would code

char _dta[datacert_vl] `varlist'

but you are worried that `varlist' might be too long for _dta[datacert_vl]. The solution is to code

mata: ado_intolchar("_dta", "datacert_vl", "varlist")

There are no typographic errors in the above. You pass the names of the entities -- including the macro -- and not their contents.

In another part of the code, you want to pull back into macro baselist what was stored in _dta[datacert_vl]. Ordinarily you would code

local baselist `_dta[datacert_vl]'

but, because you used st_intolchar(), you must not do that. Instead, you code

mata: ado_fromlchar("baselist", "_dta", "datacert_vl")

In yet another part of the program, you want to clear the characteristics. To clear _dta[datacert_vl], ordinarily you would code

char _dta[datacert_vl]

but, because you used st_intolchar(), you must not do that. Instead, you code

mata: st_lchar("_dta", "datacert_vl", "")

Example 2 -- Mata usage

In Mata code, you wish to set _dta[datacert_vl] to contain the contents of string scalar s. You code

st_lchar("_dta", "datacert_vl", s)

To read back into s what is stored in _dta[datacert_vl], you code

s = st_lchar("_dta", "datacert_vl")

To delete the characteristic _dta[datacert_vl], you code

st_lchar("_dta", "datacert_vl", "")

Conformability

st_lchar(basename, charname, s): basename: 1 x 1 charname: 1 x 1 s: 1 x 1 result: void

st_lchar(basename, charname): basename: 1 x 1 charname: 1 x 1 result: 1 x 1

ado_intolchar(basename, charname, macname): basename: 1 x 1 charname: 1 x 1 macname: 1 x 1 result: void

ado_fromlchar(macname, basename, charname): macname: 1 x 1 basename: 1 x 1 charname: 1 x 1 result: void

Diagnostics

All functions abort with error if names are malformed. Requesting the contents of a characteristic that does not exist returns "". If s is stored in a characteristic and read back, the original spacing (lack of blanks, multiple blanks, etc.) of s is preserved.

Source code

st_lchar.mata


© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index