ironwork_rt/sql/
convert.rs

1//! Host variables to values and back, by Db2's assignment rules: a number that does not fit its
2//! host variable is an error rather than a truncation, and a string that does not fit is cut and
3//! reported.
4
5use super::{BAD_LENGTH, HostType, NOT_ASSIGNABLE, OUT_OF_RANGE, SqlError, UNCONVERTIBLE, Value};
6use crate::codec;
7use crate::vocab::{SignClause, SignPosition};
8use numeric::Numproc;
9use zarch::check::ProgramCheck;
10use zarch::decimal::{self, Decimal};
11use zarch::ebcdic::CodePage;
12use zarch::hfp::{Hfp, Precision};
13
14/// Why an input host variable could not be read: its storage failed as the machine's own read
15/// would (S0C7), or Db2 refuses it with an SQLCODE.
16#[derive(Clone, Copy, Debug, PartialEq, Eq)]
17pub enum ReadError {
18    Check(ProgramCheck),
19    Sql(SqlError),
20}
21
22/// What storing an output value did besides store it: the length a cut string had, for SQLWARN1
23/// and the indicator.
24#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
25pub struct Written {
26    pub truncated_from: Option<usize>,
27}
28
29/// The value an input host variable sends. `bytes` is the host variable's storage.
30pub fn read(bytes: &[u8], ty: &HostType, page: &CodePage, numproc: Numproc) -> Result<Value, ReadError> {
31    let as_value = |d: Decimal, scale: u32| {
32        let magnitude = d.magnitude as i128;
33        Value::Decimal { value: if d.negative { -magnitude } else { magnitude }, scale }
34    };
35    Ok(match *ty {
36        HostType::SmallInt { signed } | HostType::Integer { signed } | HostType::BigInt { signed } => {
37            let v = integer(bytes, signed);
38            i64::try_from(v).map_or(Value::Decimal { value: v, scale: 0 }, Value::Int)
39        }
40        HostType::Decimal { scale, signed, .. } => as_value(codec::packed(bytes, signed, numproc).map_err(ReadError::Check)?, scale),
41        HostType::Zoned { scale, signed, sign, .. } => as_value(codec::zoned(bytes, signed, sign, numproc).map_err(ReadError::Check)?, scale),
42        HostType::Real => Value::Double(Hfp::from_bytes(Precision::Short, bytes).approx()),
43        HostType::Double => Value::Double(Hfp::from_bytes(Precision::Long, bytes).approx()),
44        HostType::Char(_) => Value::Char(page.decode(bytes)),
45        HostType::VarChar(max) => {
46            let len = i16::from_be_bytes([bytes[0], bytes[1]]);
47            if len < 0 || len as u32 > max {
48                return Err(ReadError::Sql(BAD_LENGTH));
49            }
50            Value::Char(page.decode(&bytes[2..2 + len as usize]))
51        }
52        HostType::Graphic(_) => Value::Char(page.decode_dbcs(bytes)),
53        HostType::VarGraphic(max) => {
54            let len = i16::from_be_bytes([bytes[0], bytes[1]]);
55            if len < 0 || len as u32 > max {
56                return Err(ReadError::Sql(BAD_LENGTH));
57            }
58            Value::Char(page.decode_dbcs(&bytes[2..2 + 2 * len as usize]))
59        }
60        HostType::Structure(_) => unreachable!("a host structure is read member by member"),
61    })
62}
63
64/// Stores a non-null output value into a host variable's storage, as Db2 assigns it.
65pub fn write(value: &Value, bytes: &mut [u8], ty: &HostType, page: &CodePage) -> Result<Written, SqlError> {
66    match *ty {
67        HostType::SmallInt { signed } | HostType::Integer { signed } | HostType::BigInt { signed } => store_integer(whole(value)?, bytes, signed)?,
68        HostType::Decimal { digits, scale, signed } => {
69            let v = fitted(scaled(value, scale)?, digits, signed)?;
70            decimal::encode(bytes, Decimal { negative: v < 0, magnitude: v.unsigned_abs() }).expect("a packed host variable is 1 to 16 bytes");
71            if !signed {
72                *bytes.last_mut().unwrap() |= 0x0F;
73            }
74        }
75        HostType::Zoned { digits, scale, signed, sign } => store_zoned(fitted(scaled(value, scale)?, digits, signed)?, bytes, digits, signed, sign),
76        HostType::Real => bytes.copy_from_slice(&hfp_image(float(value)?, Precision::Short).ok_or(OUT_OF_RANGE)?),
77        HostType::Double => bytes.copy_from_slice(&hfp_image(float(value)?, Precision::Long).ok_or(OUT_OF_RANGE)?),
78        HostType::Char(_) => return store_text(&text(value, page)?, bytes, page),
79        HostType::VarChar(max) => {
80            let t = text(value, page)?;
81            let n = t.len().min(max as usize);
82            bytes[..2].copy_from_slice(&(n as u16).to_be_bytes());
83            bytes[2..2 + n].copy_from_slice(&t[..n]);
84            return Ok(Written { truncated_from: (t.len() > n).then_some(t.len()) });
85        }
86        HostType::Graphic(len) => {
87            let t = graphic(value, page)?;
88            let n = t.len().min(2 * len as usize);
89            bytes[..n].copy_from_slice(&t[..n]);
90            bytes[n..].fill(0x40);
91            return Ok(Written { truncated_from: (t.len() > n).then_some(t.len() / 2) });
92        }
93        HostType::VarGraphic(max) => {
94            let t = graphic(value, page)?;
95            let n = t.len().min(2 * max as usize);
96            bytes[..2].copy_from_slice(&((n / 2) as u16).to_be_bytes());
97            bytes[2..2 + n].copy_from_slice(&t[..n]);
98            return Ok(Written { truncated_from: (t.len() > n).then_some(t.len() / 2) });
99        }
100        HostType::Structure(_) => unreachable!("a host structure is written member by member"),
101    }
102    Ok(Written::default())
103}
104
105fn integer(bytes: &[u8], signed: bool) -> i128 {
106    let unsigned = bytes.iter().fold(0u128, |acc, &b| acc << 8 | u128::from(b)) as i128;
107    if signed && bytes[0] & 0x80 != 0 { unsigned - (1i128 << (8 * bytes.len())) } else { unsigned }
108}
109
110fn pow10(n: u32) -> Option<i128> {
111    10i128.checked_pow(n)
112}
113
114/// The value as a whole number, fractional digits dropped.
115fn whole(value: &Value) -> Result<i128, SqlError> {
116    match *value {
117        Value::Int(v) => Ok(v.into()),
118        Value::Decimal { value, scale } => Ok(value / pow10(scale).ok_or(OUT_OF_RANGE)?),
119        Value::Double(f) if f.is_finite() && f.abs() < 1e38 => Ok(f.trunc() as i128),
120        Value::Double(_) => Err(OUT_OF_RANGE),
121        _ => Err(NOT_ASSIGNABLE),
122    }
123}
124
125/// The value unscaled at `scale` places, extra places dropped.
126fn scaled(value: &Value, scale: u32) -> Result<i128, SqlError> {
127    match *value {
128        Value::Int(v) => i128::from(v).checked_mul(pow10(scale).ok_or(OUT_OF_RANGE)?).ok_or(OUT_OF_RANGE),
129        Value::Decimal { value, scale: from } if from >= scale => Ok(value / pow10(from - scale).ok_or(OUT_OF_RANGE)?),
130        Value::Decimal { value, scale: from } => value.checked_mul(pow10(scale - from).ok_or(OUT_OF_RANGE)?).ok_or(OUT_OF_RANGE),
131        Value::Double(f) => {
132            let v = (f * 10f64.powi(scale as i32)).trunc();
133            if v.is_finite() && v.abs() < 1e38 { Ok(v as i128) } else { Err(OUT_OF_RANGE) }
134        }
135        _ => Err(NOT_ASSIGNABLE),
136    }
137}
138
139fn fitted(v: i128, digits: u32, signed: bool) -> Result<i128, SqlError> {
140    if (!signed && v < 0) || v.unsigned_abs() >= pow10(digits).ok_or(OUT_OF_RANGE)?.unsigned_abs() { Err(OUT_OF_RANGE) } else { Ok(v) }
141}
142
143fn store_integer(v: i128, bytes: &mut [u8], signed: bool) -> Result<(), SqlError> {
144    let bits = 8 * bytes.len() as u32;
145    let (low, high) = if signed { (-(1i128 << (bits - 1)), (1i128 << (bits - 1)) - 1) } else { (0, (1i128 << bits) - 1) };
146    if !(low..=high).contains(&v) {
147        return Err(OUT_OF_RANGE);
148    }
149    let image = v as u128;
150    for (i, b) in bytes.iter_mut().rev().enumerate() {
151        *b = (image >> (8 * i)) as u8;
152    }
153    Ok(())
154}
155
156/// Zoned digits through UNPK, then the sign where the SIGN clause puts it.
157fn store_zoned(v: i128, bytes: &mut [u8], digits: u32, signed: bool, sign: Option<SignClause>) {
158    let negative = v < 0;
159    let mut packed = vec![0u8; digits as usize / 2 + 1];
160    decimal::encode(&mut packed, Decimal { negative, magnitude: v.unsigned_abs() }).expect("the packed image holds the item's digits");
161    let unpack = |zoned: &mut [u8]| decimal::unpk(zoned, &packed).expect("a zoned host variable is 1 to 16 bytes");
162    match sign {
163        Some(SignClause { separate: true, position }) => {
164            let n = bytes.len();
165            let (sign_at, digits_at) = if position == SignPosition::Leading { (0, 1..n) } else { (n - 1, 0..n - 1) };
166            unpack(&mut bytes[digits_at.clone()]);
167            bytes[digits_at.end - 1] |= 0xF0;
168            bytes[sign_at] = if negative { 0x60 } else { 0x4E };
169        }
170        Some(SignClause { separate: false, position: SignPosition::Leading }) => {
171            unpack(bytes);
172            let last = bytes.len() - 1;
173            let zone = bytes[last] & 0xF0;
174            bytes[last] |= 0xF0;
175            bytes[0] = zone | (bytes[0] & 0x0F);
176        }
177        _ => {
178            unpack(bytes);
179            if !signed {
180                *bytes.last_mut().unwrap() |= 0xF0;
181            }
182        }
183    }
184}
185
186fn float(value: &Value) -> Result<f64, SqlError> {
187    match *value {
188        Value::Int(v) => Ok(v as f64),
189        Value::Decimal { value, scale } => Ok(value as f64 / 10f64.powi(scale as i32)),
190        Value::Double(f) => Ok(f),
191        _ => Err(NOT_ASSIGNABLE),
192    }
193}
194
195/// An IEEE double as a hexadecimal floating-point storage image, low-order bits that do not fit
196/// the short form dropped (assumption SQ9). None when the exponent is outside HFP's range.
197fn hfp_image(f: f64, precision: Precision) -> Option<Vec<u8>> {
198    let len = precision.bytes();
199    if f == 0.0 {
200        return Some(vec![0; len]);
201    }
202    if !f.is_finite() {
203        return None;
204    }
205    let bits = f.to_bits();
206    let raw_exponent = ((bits >> 52) & 0x7FF) as i32;
207    let (mantissa, exponent) = match raw_exponent {
208        0 => (bits & ((1 << 52) - 1), -1074),
209        e => ((bits & ((1 << 52) - 1)) | 1 << 52, e - 1075),
210    };
211    let top = exponent + (64 - mantissa.leading_zeros() as i32);
212    let hex = top.div_euclid(4) + i32::from(top.rem_euclid(4) != 0);
213    let characteristic = hex + 64;
214    if !(0..=127).contains(&characteristic) {
215        return None;
216    }
217    let fraction_bits = if precision == Precision::Short { 24 } else { 56 };
218    let shift = exponent + fraction_bits - 4 * hex;
219    let fraction = if shift >= 0 { mantissa << shift } else { mantissa >> -shift };
220    let lead = u64::from(f.is_sign_negative()) << 7 | characteristic as u64;
221    Some(match precision {
222        Precision::Short => ((lead << 24 | fraction) as u32).to_be_bytes().to_vec(),
223        _ => (lead << 56 | fraction).to_be_bytes().to_vec(),
224    })
225}
226
227fn text(value: &Value, page: &CodePage) -> Result<Vec<u8>, SqlError> {
228    match value {
229        Value::Char(s) => page.encode(s).map_err(|_| UNCONVERTIBLE),
230        Value::Binary(b) => Ok(b.clone()),
231        _ => Err(NOT_ASSIGNABLE),
232    }
233}
234
235/// A value's DBCS characters, two bytes each, in the code page's DBCS component; under a page with
236/// none, or for a character it lacks, the value cannot be converted (assumption
237/// [`numeric::assumptions::DBCS_HOST_VARIABLES`]).
238fn graphic(value: &Value, page: &CodePage) -> Result<Vec<u8>, SqlError> {
239    match value {
240        Value::Char(s) => page.dbcs().ok_or(UNCONVERTIBLE)?.encode(s, page.ccsid).map_err(|_| UNCONVERTIBLE),
241        _ => Err(NOT_ASSIGNABLE),
242    }
243}
244
245/// A fixed-length string: padded with the code page's space, or cut and reported.
246fn store_text(t: &[u8], bytes: &mut [u8], page: &CodePage) -> Result<Written, SqlError> {
247    let n = t.len().min(bytes.len());
248    bytes[..n].copy_from_slice(&t[..n]);
249    bytes[n..].fill(page.encode_char(' ').unwrap_or(0x40));
250    Ok(Written { truncated_from: (t.len() > bytes.len()).then_some(t.len()) })
251}
252
253#[cfg(test)]
254mod tests {
255    use super::*;
256
257    fn page() -> &'static CodePage {
258        CodePage::by_ccsid(37).expect("CCSID 37 is carried")
259    }
260
261    fn get(bytes: &[u8], ty: &HostType) -> Result<Value, ReadError> {
262        read(bytes, ty, page(), Numproc::Nopfd)
263    }
264
265    fn put(value: Value, len: usize, ty: &HostType) -> (Vec<u8>, Result<Written, SqlError>) {
266        let mut bytes = vec![0xEE; len];
267        let r = write(&value, &mut bytes, ty, page());
268        (bytes, r)
269    }
270
271    const S5V2_PACKED: HostType = HostType::Decimal { digits: 7, scale: 2, signed: true };
272
273    #[test]
274    fn graphic_host_variables_are_dbcs_characters_through_the_code_page() {
275        let p939 = CodePage::by_ccsid(939).expect("CCSID 939 is carried");
276        assert_eq!(read(&[0x44, 0x81, 0x40, 0x40], &HostType::Graphic(2), p939, Numproc::Nopfd), Ok(Value::Char("あ\u{3000}".into())));
277        let mut bytes = vec![0xEE; 4];
278        assert_eq!(write(&Value::Char("日本語".into()), &mut bytes, &HostType::Graphic(2), p939), Ok(Written { truncated_from: Some(3) }));
279        assert_eq!(&bytes[..2], [0x45, 0x62]);
280        assert_eq!(write(&Value::Char("あ".into()), &mut bytes, &HostType::Graphic(2), p939), Ok(Written::default()));
281        assert_eq!(bytes, [0x44, 0x81, 0x40, 0x40], "padded with the DBCS space");
282        let mut varying = vec![0xEE; 8];
283        assert_eq!(write(&Value::Char("あ".into()), &mut varying, &HostType::VarGraphic(3), p939), Ok(Written::default()));
284        assert_eq!(&varying[..4], [0x00, 0x01, 0x44, 0x81]);
285        assert_eq!(read(&varying, &HostType::VarGraphic(3), p939, Numproc::Nopfd), Ok(Value::Char("あ".into())));
286        assert_eq!(read(&[0x00, 0x04, 0, 0, 0, 0, 0, 0], &HostType::VarGraphic(3), p939, Numproc::Nopfd), Err(ReadError::Sql(BAD_LENGTH)));
287        assert_eq!(put(Value::Char("あ".into()), 4, &HostType::Graphic(2)).1, Err(UNCONVERTIBLE), "CCSID 37 has no DBCS characters");
288    }
289
290    #[test]
291    fn binary_host_variables() {
292        assert_eq!(get(&[0xFF, 0xFE], &HostType::SmallInt { signed: true }), Ok(Value::Int(-2)));
293        assert_eq!(get(&[0xFF, 0xFE], &HostType::SmallInt { signed: false }), Ok(Value::Int(65534)));
294        assert_eq!(get(&[0, 0, 1, 0], &HostType::Integer { signed: true }), Ok(Value::Int(256)));
295        assert_eq!(put(Value::Int(-2), 2, &HostType::SmallInt { signed: true }).0, [0xFF, 0xFE]);
296        assert_eq!(put(Value::Int(40_000), 2, &HostType::SmallInt { signed: true }).1, Err(OUT_OF_RANGE));
297        assert_eq!(put(Value::Int(-1), 4, &HostType::Integer { signed: false }).1, Err(OUT_OF_RANGE));
298        assert_eq!(put(Value::Decimal { value: 12_399, scale: 2 }, 4, &HostType::Integer { signed: true }).0, [0, 0, 0, 123]);
299    }
300
301    #[test]
302    fn packed_host_variables() {
303        assert_eq!(get(&[0x01, 0x23, 0x45, 0x0D], &S5V2_PACKED), Ok(Value::Decimal { value: -123_450, scale: 2 }));
304        assert_eq!(get(&[0x01, 0x23, 0x45, 0x0A << 4], &S5V2_PACKED), Err(ReadError::Check(ProgramCheck::Data)));
305        assert_eq!(put(Value::Decimal { value: -123_450, scale: 2 }, 4, &S5V2_PACKED).0, [0x01, 0x23, 0x45, 0x0D]);
306        assert_eq!(put(Value::Decimal { value: 1_239, scale: 3 }, 4, &S5V2_PACKED).0, [0x00, 0x00, 0x12, 0x3C]);
307        assert_eq!(put(Value::Decimal { value: 12_345_600, scale: 2 }, 4, &S5V2_PACKED).1, Err(OUT_OF_RANGE));
308        assert_eq!(put(Value::Int(7), 2, &HostType::Decimal { digits: 3, scale: 0, signed: false }).0, [0x00, 0x7F]);
309    }
310
311    #[test]
312    fn zoned_host_variables() {
313        let trailing = HostType::Zoned { digits: 5, scale: 0, signed: true, sign: None };
314        assert_eq!(put(Value::Int(-123), 5, &trailing).0, [0xF0, 0xF0, 0xF1, 0xF2, 0xD3]);
315        assert_eq!(get(&[0xF0, 0xF0, 0xF1, 0xF2, 0xD3], &trailing), Ok(Value::Decimal { value: -123, scale: 0 }));
316        let leading_separate = HostType::Zoned { digits: 5, scale: 0, signed: true, sign: Some(SignClause { position: SignPosition::Leading, separate: true }) };
317        assert_eq!(put(Value::Int(-123), 6, &leading_separate).0, [0x60, 0xF0, 0xF0, 0xF1, 0xF2, 0xF3]);
318        assert_eq!(get(&[0x60, 0xF0, 0xF0, 0xF1, 0xF2, 0xF3], &leading_separate), Ok(Value::Decimal { value: -123, scale: 0 }));
319        let leading = HostType::Zoned { digits: 3, scale: 0, signed: true, sign: Some(SignClause { position: SignPosition::Leading, separate: false }) };
320        assert_eq!(put(Value::Int(45), 3, &leading).0, [0xC0, 0xF4, 0xF5]);
321    }
322
323    #[test]
324    fn strings_pad_cut_and_report() {
325        let (bytes, r) = put(Value::Char("ABCDEFGHIJ".into()), 5, &HostType::Char(5));
326        assert_eq!((page().decode(&bytes), r), ("ABCDE".into(), Ok(Written { truncated_from: Some(10) })));
327        let (bytes, r) = put(Value::Char("AB".into()), 5, &HostType::Char(5));
328        assert_eq!((page().decode(&bytes), r), ("AB   ".into(), Ok(Written::default())));
329        let (bytes, r) = put(Value::Char("HELLO".into()), 5, &HostType::VarChar(3));
330        assert_eq!((bytes[..2].to_vec(), page().decode(&bytes[2..]), r), (vec![0, 3], "HEL".into(), Ok(Written { truncated_from: Some(5) })));
331        let mut varchar = vec![0, 2];
332        varchar.extend(page().encode("OKXX").unwrap());
333        assert_eq!(get(&varchar, &HostType::VarChar(4)), Ok(Value::Char("OK".into())));
334        assert_eq!(get(&[0, 9, 0xC1, 0xC1], &HostType::VarChar(2)), Err(ReadError::Sql(BAD_LENGTH)));
335        assert_eq!(put(Value::Int(1), 5, &HostType::Char(5)).1, Err(NOT_ASSIGNABLE));
336        assert_eq!(put(Value::Char("1".into()), 2, &HostType::SmallInt { signed: true }).1, Err(NOT_ASSIGNABLE));
337    }
338
339    #[test]
340    fn floats_cross_between_ieee_and_hfp() {
341        assert_eq!(put(Value::Double(1.0), 8, &HostType::Double).0, [0x41, 0x10, 0, 0, 0, 0, 0, 0]);
342        assert_eq!(put(Value::Double(-2.5), 8, &HostType::Double).0, [0xC1, 0x28, 0, 0, 0, 0, 0, 0]);
343        assert_eq!(put(Value::Double(0.0), 4, &HostType::Real).0, [0, 0, 0, 0]);
344        assert_eq!(put(Value::Double(0.5), 4, &HostType::Real).0, [0x40, 0x80, 0, 0]);
345        for f in [1.0, -2.5, 0.1, 1234.5678, 1e-20, 6.02e23] {
346            let (bytes, _) = put(Value::Double(f), 8, &HostType::Double);
347            let Ok(Value::Double(back)) = get(&bytes, &HostType::Double) else { panic!() };
348            assert!((back - f).abs() <= f.abs() * 1e-15, "{f} came back as {back}");
349        }
350        assert_eq!(put(Value::Double(1e300), 8, &HostType::Double).1, Err(OUT_OF_RANGE));
351    }
352}
ironwork_rt/sql/convert.rs

ironwork_rt/sql/
convert.rs
